2. troff, groff, 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, here used to produce a drop capital colored terracotta pink. The syntax recognized is the improved kind supported by groff, Heirloom troff, and Neatroff, 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. In order to avoid constantly qualifying my sentences, I shall henceforth use groff as the troff implementation to work alongside Troff2page. There will be some modification needed when using other troff implementations.

The request .pm lists on the console, in alphabetical order, all the requests, macros, and strings defined by Troff2page. You can then search for their behavior in the Troff2page and/or groff manuals.

mpca macro files

Troff2page can process documents that use the general-purpose ms extension macros provided in mpca. `mpca` macro files include: pca-bib.tmac for bibliographic citations; pca-dc.tmac for drop caps; pca-eval.tmac for extending groff using Lua; pca-img.tmac for image insertion; pca-ix.tmac for index generation; pca-tag.tmac for cross-references; pca-toc.tmac for table of contents; pca-verb.tmac for verbatim displays. These extensions may be loaded severally or as the single comprehensive macro file pca.tmac. To load them all, use the command-line option -mpca or include .mso pca.tmac in your document source. Please consult the `mpca` documentation for more information.

In order to take advantage of the mpca tmac files, you should place them in one of your groff macro directories. (Both groff and Troff2page search for macro files first in the directories in GROFF_TMAC_PATH, then in the working directory, and finally in your home directory. See the section for “Macro Directories” in the groff info file for details.)

Your input document sources the mpca macro files using either the -m command-line option or the .mso request.

Auxiliary files

Many of the macros defined in these .tmac files write auxiliary files that are absorbed into the document during a second run. Let’s first investigate how groff deals with them, and then see how Troff2page does the same in its own way. Note that in order to write these aux files, groff must be run with the -U option for “unsafe” mode.

As an example, consider index.ms (the groff source for the document you’re reading, which is the doc subdirectory). The following is one way to get the correct PostScript output:

The -t option (which calls the tbl preprocessor) is needed because the document index.ms 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 programs 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 also needs to process the document twice in order to absorb information from the aux files. However:

i. Troff2page will automatically do the second processing without needing the user to explicitly call it a second time; and

ii. Troff2page doesn’t need any special option to run in “unsafe” mode or to process tables.

The same holds if you run Troff2page by calling the Lua procedure troff2page within Lua, as described on page 1.

If you wish to have the Lua procedure perform just one pass on the document, set the global Single_pass_p to true, i.e.,

Call it the same way a second time to run the second pass, which resolve the aux files. This is exactly analogous to calling groff twice on the same document to resolve aux files.

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 “.troff2page_temp_Jobname” for Troff2page, where Jobname is the basename of the main input document file.

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 groff 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.