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, here used to produce a drop cap colored terracotta pink. 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.1 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; eval4troff.tmac for extending troff using Common Lisp; and defhsl.tmac for defining color names using the HSL scheme. You should put these .tmac files in one of your macro directories, i.e., the directories that are searched by groff’s -m option and .mso request. (See the section for “Macro Directories” in the groff info file for details. In a pinch, your home directory works as a macro directory.)

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 index.ms (the groff source for the document you’re reading). The following is one way to get the correct PostScript output:

    % groff -t -U -z index.ms
    defhsl.tmac:8: can’t open ‘.trofftemp_lisp_1.tmp’ ...
    Rerun groff with -U
    index.ms:187: can’t open ‘.trofftemp.aux’ ...
    index.ms:799: can’t open ‘.trofftemp.ind’ ...

    % groff -t -U index.ms > index.ps

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

    % troff2page index.ms
    Missing: (.troff2page_temp_index.ind .troff2page_temp_index.aux
    LAST-PAGE-NUMBER TOC TITLE .troff2page_temp_index_lisp_1.tmp)
    Rerun: troff2page index.ms

    % troff2page index.ms

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.

Simulating troff options

The program troff2page just takes a single argument. Typically this is a filename specifying the input document file. If the file so named does not exist, troff2page exits with a “could not find” message.

The only exceptions are when the argument is --help or --version, in which case troff2page displays an appropriate informative text and exits. For example,

    % troff2page --help
    troff2page version 20111124
    Copyright (C) ...
    For full details, please see http://www...

While this is intentionally similar to groff’s --help and --version options, troff2page cannot process true options as groff can. Indeed, if --help and --version happen to be the names of input documents, troff2page will process them as such.

In contrast, groff options allow you to specify on the command-line not just the input file but also additional information, e.g., -m to load macro files; -r to pre-set number registers; -d to pre-define strings; -f to set default font family; etc. (Please see the groff man page for details on all the provided options.) The options can be usefully varied with each call to groff.

For options that do not make sense for HTML — e.g., the setting of PO (adjusting the left margin to suit a particular printer) —, it is fine that they cannot also be fed to troff2page. For the options that are valid for both print and HTML — e.g., loading a macro file that works for both output formats —, you may need to add this information explicitly within the input document. Thus, a -m command-line option would be replaced by an explicit call to .mso within the document.

However, this will not be a workable approach for some options that do not quite belong to the document, or that may potentially need to be varied for the same document, when processed by different users or in different environments, e.g., settings for registers like GROWPS and PSINCR. For such cases, you may place the information in a troff macro file .troff2pagerc.tmac in your home directory. troff2page will load this file, if it exists, before processing its argument file.

(Note that groff or troff will not load .troff2pagerc.tmac automatically. But that is presumably OK, since you are using command-line options to specify the same information anyway. If you do want groff to pick up this file, you can use the option -m.troff2pagerc.)

If the input file is recognizably a man page (i.e., it has the command .TH), both troff2page and groff will load, if it exists, the init file man.local in the home directory.


1 E.g., ms’s footnotes (\** and .FS/.FE) have a straightforward translation in the HTML, with the footnote text set at the bottom of the HTML page, and with the footnote markers in the body and the footnote hyperlinking to each other.