2.  troff and troff2page commands

TROFF2PAGE recognizes most of the commands (requests, macros, diversions, strings, escapes, glyphs) of raw troff and its ms and man macro packages, including such rather recherché macros as .DC, which produces colored drop caps. The syntax recognized is the improved kind supported by groff and Heirloom troff, i.e., macro, string, and glyph names can be arbitrarily long, and strings can have arguments. Most of the commands are converted to their obvious HTML equivalent.¹ Please consult troff and groff documentation for these commands. We will concentrate here on those commands whose HTML counterpart is not immediately obvious.

The troff2page distribution includes several files with extension tmac, viz., url.tmac for inserting hyperlinks, index.tmac for index generation, and eval4troff.tmac for extending troff using Common Lisp. You may wish to put these .tmac files in your GROFF_TMAC_PATH.

Note that it is best to load these .tmac files into your document with an .mso request rather than through groff’s command-line option -m. This is because troff2page doesn’t support the same kind of command-line arguments that groff does.

Auxiliary files

Many of the macros defined in these .tmac files write auxiliary files that are absorbed into the document during a second run. Note that in order to write these aux files, groff must be run with the -U option for “unsafe” mode.

As an example, consider troff2page.1 (the groff source for the document you’re reading), which uses url.tmac, index.tmac, and eval4troff.tmac. The following is one way to get the correct PostScript output:

The -t option (which calls the tbl preprocessor) is needed because the document troff2page.1 uses a table. The first run uses the -z option to disable writing an output file, which we don’t need until the second run.

In both runs, we use the -U option: The first run needs unsafe mode to write the aux files, and the second run needs it to process some of them with external progams to create additional aux files. Subsequent runs may dispense with the -U, as all the required aux files are made. (You will need the option again, if the aux files’ content changes.)

troff2page is also run twice on the document to absorb information from the aux files. However, troff2page doesn’t need any special option as it is always run in what groff would consider “unsafe” mode, and it processes tables by itself.

The groff string \*[AUXF] is used to construct the names of the auxiliary files. By default it will be quietly set to .trofftemp for groff and something slightly different for troff2page. You can change it to anything else in your document before the first use of any macros that use or write aux files. It is a good idea to set it so that it remains different for troff and troff2page, so that the two programs’ aux files don’t clash. The number register \n[.troff2page] (page 3) suggests a way to do this.