6 ms·
The TXR manual is written in troff. It's designed so that you can install it as a man page, but it has macros which retarget some of the formatting for HTML and
by kazinator 4y ago
The TXR manual is written in troff. It's designed so that you can install it as a man page, but it has macros which retarget some of the formatting for HTML and PDF. When compiled to PDF, it comes out to over 900 pages.
It may be the only man page you will ever see which auto-numbers its sections (down to three levels deep). I developed the macros for all that.
Pretty much any large or large-ish man page you can think of does not have this feature. E.g. type "man gcc" or "man bash": no section numbers anywhere.
I use Lucifredi's man2html converter from the man1.6 package. I think this is mostly abandonware. The man2html program is essentially a hacky reimplementation of enough of a subset of nroff to crank simple man pages into HTML. It does a better job than any other converter. (There is at least one more thing called man2html, like one unrelated program written in Perl.)
I made some 30 commits to man2html, fixing bugs, adding some features, and making it understand and execute complex nroff macro definitions. One feature added is that man2html defines a variable M2 which the code can use to conditionally switch to code specific to man2html versus regular nroff. All that work is here:
https://www.kylheku.com/cgit/man/log/ https://www.kylheku.com/cgit/man/log/
Anyone wanting to reproduce the HTML version of the TXR manual needs that version of man2html. A TXR program called genman.txr, in the root of the TXR source tree, analyzes the man2html output, and rearranges it, adds identifier cross-referencing, a collapsible table of contents (via a tiny bit of JS) and such.
I use another TXR program for running checks for common markup mistakes in the manual: checkman.txr in the root of the TXR source tree. It understands the usage of many of my custom macros and validates that they are correctly used, in their intended structures. For instance if a syntax synopsis block is opened with .synb, it will tell you there is a missing .syne closer.
There are "weird" formatting macros; e.g:
.coNP Operators @ let and @ let*
.synb
.mets (let >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.mets (let* >> ({ sym | >> ( sym << init-form )}*) << body-form *)
.syne
.desc
The
.code let
and
.code let*
operators introduce ...
coNP is like NP, introducing a paragraph at a certain subsection level; the co refers to it having code markup. In co markup, a word preceded by @ will be typeset as code, e.g. typewriter font. A word preceded by @, (at comma) will be typeset in a typewriter font, followed immediately by a comma in the original font.
.synb starts the syntax synopsis section and .synb ends it.
We use .mets for markup in the syntax synopsis. The "met" refers to "meta": markup for meta-syntactic identifiers, which typically use italic in HTML and PDF of angle brackets like <sym> in the plain text man page.
In .mets, everything is typewriter by default. When an argument is preceded by <, it is marked up as a meta identifier, italic or <angle>. When two arguments are preceded by <<, like << body-form *) the left one is meta, and the right one is tacked onto it with no intervening space. There is also <> with three arguments: <> A B C will typeset B as a meta, flanked by A and C with no space; and there is an opposite >< also.
All these macros are defined near the top of the txr.1 file.
The "meta" markup is implemented by lower-level macro called .getm which the higher level ones like .mets and .meti and .meIP use. That macro is implemented twice, conditionally switched for nroff mode (angle brackets) and regular (font switching).
- kazinator 4y agoIn the documentations sections describing the REPL, I wanted to nicely typeset keystroke sequences with <kbd>...</kbd>. The result is that there two macros: .key foo foo will be typeset as a keycap, with spaces around it, and: .keyn foo bar foo typeset as keycap, immediately followed by bar (no intervening space) by regular bar. The macros are defined in three ways: one for man2html, one for nroff, and one for groff: .\" keystrokes .ie \n(M2 \{\ .de key .M2HT <kbd>\\$1</kbd> .. .de keyn .M2HT <kbd>\\$1</kbd>\\$2 .. .\} That's for man2html, detected by the M2 variable being nonzero. (This elicits a warning out of groff, due to that variable not existing.) We use the .M2HT macro for inline HTML. I think that didn't exist in man2html; another thing I added. .el \{\ . ie n \{\ . de key [\\$1] . . . de keyn [\\$1]\\$2 . . . \} Else, for the other two: first nroff for man page viewing. Here the strategy is to use square brackets, so .key Ctrl becomes [Ctrl]. . el \{\ . \" Box macro from Groff manual with $2 added . de box . nr @wd \w'\\$1' \h'.2m'\ \h'-.2m'\v'(.2m - \\n[rsb]u)'\ \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ \D'l (\\n[@wd]u + .4m) 0'\ \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ \D'l -(\\n[@wd]u + .4m) 0'\ \h'.2m'\v'-(.2m - \\n[rsb]u)'\ \\$1\ \h'.2m'\\$2 . . . de key . box "\\$1" "" . . . de keyn . box "\\$1" "\\$2" . . . \} .\} For groff PDF output we use a .box macro to put a box around the keycap material. The macro is based on something in the manual. Not sure why the box invocations are indented funny.