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 troff macro or tmac files (with extension tmac), both in the main directory and in the sudirectory for the submodule mpca. They include general-purpose extensions to the ms package, e.g., pca-tag.tmac for cross-references; pca-ix.tmac for index generation; pca-eval.tmac for extending troff using Lua, etc.

You should put these tmac files in one of your macro directories, i.e., the directories that are searched by the -m command-line option and .mso request. (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.)

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:

    % groff -t -U -z index.ms
    Rerun groff with -U
    index.ms:18: can't open `.trofftemp.toc': No such file or directory
    index.ms:38: can't open `.trofftemp.ind': No such file or directory

    % groff -t -U index.ms > index.ps
    This is makeindex, version 2.15 [TeX Live 2016] (kpathsea + Thai support).
    Scanning style file ./.trofftemp.mst...............done (15 attributes redefined, 0 ignored).
    Scanning input file z.trofftemp.idx....done (61 entries accepted, 0 rejected).
    Sorting entries....done (393 comparisons).
    Generating output file z.trofftemp.ind....done (132 lines written, 0 warnings).
    Output written in z.trofftemp.ind.
    Transcript written in z.trofftemp.ilg.

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:

(1) troff2page will automatically do the second processing without needing the user to explicitly call it a second time; and

(2) troff2page doesn’t need any special option to run in “unsafe” mode or to process tables.

    % troff2page index.ms
    index.ms:18: cannot open .troff2page_temp_index.toc: No such file or directory
    index.ms:38: can't open .troff2page_temp_index.ind: No such file or directory
    Missing: {eval, stylesheet, title, toc, .troff2page_temp_index.toc, last_page_number, index}
    Rerunning: troff2page index.ms
    This is makeindex, version 2.15 [TeX Live 2016] (kpathsea + Thai support).
    Scanning style file ./.troff2page_temp_index.mst...............done (15 attributes redefined, 0 ignored).
    Scanning input file z.troff2page_temp_index.idx....done (61 entries accepted, 0 rejected).
    Sorting entries....done (406 comparisons).
    Generating output file z.troff2page_temp_index.ind....done (151 lines written, 0 warnings).
    Output written in z.troff2page_temp_index.ind.
    Transcript written in z.troff2page_temp_index.ilg.

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

    Single_pass_p = true

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

Commmand-line options

troff2page takes some, but not all, of the same options as groff, viz., -v or --version to display the version; -h or --help to display help; -m to load macro files from GROFF_TMAC_PATH; -r to pre-set number registers; -d to pre-define strings; and -- to signal the end of options.

The options can be varied with each call to troff2page, just as with groff. Please see the groff man page for details on all the provided options.

troff2page ignores all other groff options, most with a warning. The options -z, -t, and -U are silently ignored, as they're always valid for troff2page.

    % troff2page --help
    troff2page version 20170827
    Copyright (C) ...
    For full details, please see http://ds26gte.github.io/troff2page

In the unlikely event that you have a document file named --help (and wish to process it), use use

    % troff2page -- --help

Macro file options must be given without the suffix .tmac or prefix tmac.. Thus, -mxyz or -m xyz looks for the macro file xyz.tmac or tmac.xyz, whichever is found in the macro directories, and loads it.

If after all the option processing, no file arguments remain, troff2page displays a “could not find” message.

If you find you need to specify an option that troff2page doesn't accept, you can always supply it in a macro file via -m.

troff2page can read directives in some autoloaded files without the need to explicitly use a command-line option. These are useful to specify information that is relevant only the HTML output.

The first such file is named .troff2pagerc.tmac, placed in one of your macro directories (GROFF_TMAC_PATH, working directory, home). The working directory is a good location if your changes are geared to only those documents that are in that directory. If your changes will be used in all your documents, place it in your home or a private GROFF_TMAC_PATH directory. A more system-level GROFF_TMAC_PATH placement is typically unadvised for such an ad hoc file.

troff2page loads the first .troff2pagerc.tmac it finds, if it exists, before processing its main argument file.

In addition, troff2page will also pick up a file jobname.t2p, where jobname is the basename of the input document. This is useful for directives that are specific to a document. Note that the jobname.t2p, unlike .troff2pagerc.tmac, is looked for only in the working directory, and not more generally in GROFF_TMAC_PATH.

(Note that groff itself will not load either .troff2pagerc.tmac or jobname.t2p automatically. But that is presumably OK, since you are using groff command-line options to specify the same information anyway, or these files contain information that's only relevant for HTML. 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.