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 Common Lisp, etc.

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. (groff searches 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.)

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. But see below for avoiding cluttering your source document.

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, 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 2015] (kpathsea + Thai support).
    Scanning style file ./.trofftemp.mst...............done (15 attributes redefined, 0 ignored).
    Scanning input file z.trofftemp.idx....done (58 entries accepted, 0 rejected).
    Sorting entries....done (343 comparisons).
    Generating output file z.trofftemp.ind....done (128 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: can’t open ‘.troff2page_temp_index.toc’: No such file or directory
    index.ms:932: can’t open ‘.troff2page_temp_index.ind’: No such file or directory
    Missing: (.troff2page_temp_index.ind INDEX LAST-PAGE-NUMBER
              .troff2page_temp_index.toc TOC TITLE STYLESHEET)
    Rerunning: troff2page index.ms
    This is makeindex, version 2.15 [TeX Live 2015] (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 (58 entries accepted, 0 rejected).
    Sorting entries....done (338 comparisons).
    Generating output file z.troff2page_temp_index.ind....done (141 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 CL procedure troff2page:troff2page within CL, as described on page 1.

If you wish to have the CL procedure perform just one pass on the document, give it a second argument that is non-false, e.g.,

    (troff2page:troff2page "index.ms" :single-pass)

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.

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 20160216
    Copyright (C) 2003-2016 Dorai Sitaram
    For full details, please see http://ds26gte.github.io/troff2page/index.html

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 you can’t feed the same option 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 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, or if you simply do not want to clutter your document source.

For such cases, you may place the information in a file named troff2pagerc.tmac in one of your macro directories (GROFF_TMAC_PATH, working directory, home). The working directory is usual if your changes are geared to your document. A home-directory or private GROFF_TMAC_PATH placement is also plausible if your changes are valid for all your documents. 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.

(Note that groff itself will not load .troff2pagerc.tmac automatically. But that is presumably OK, since you are using groff 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.