4. Cross-references

Troff2page provides a .TAG macro for managing cross-references. A compatible groff definition is provided in the supplied macro file pca-tag.tmac. (This overrides the similarly named macro in groff’s www.tmac, in order to allow forward references.)

    .TAG sec_trofflua

associates the tag sec_trofflua with the number of the current page. The string \*[TAG:sec_trofflua] is defined to typeset as that page number. Thus, in a hand-crafted table of contents, you could use

    Extending groff using Lua, \*[TAG:sec_trofflua]

In the HTML output, the string \*[TAG:sec_trofflua] furthermore is a link to where .TAG sec_trofflua was called.

The pca macros use tags for internal bookkeeping: to avoid name clashes, don’t start your own tags with two underscores.

.TAG takes an optional second argument. The tag is then associated with the text of the second argument instead of the current page number.


The macro file pca-toc.tmac supplies a .ToC macro for automatic generation of a table of contents. This can be used by both groff and Troff2page.

For both outputs, ToC entries are created for headers of level \n[GROWPS] or lower. By default, GROWPS is set to 0, so you should set it to at least 1 to see a ToC.

The original purpose of GROWPS was to govern the font-size of headers at levels below it, provided it is set to at least 2 and the register \n[PSINCR] is set (which it is, by default, to 1p). Troff2page respects this too. If you’d rather use CSS to affect section-header style, including font-size, but you must have GROWPS ≥ 2 because your ToC requires it, then conditionally set PSINCR to 0.

    .if \n[.troff2page] .nr PSINCR 0

pca-toc.tmac doesn’t require you to modify how you use your header macros (.SH or .NH). It is a solution to the following statement from the groff manual:

Altering the ‘NH’ macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use ‘ms’ regularly.

Troff2page autoloads the macro file pca-t2p-man.tmac (if it can find it in GROFF_TMAC_PATH) to automatically generate a ToC for man pages, with a ToC entry for each .SH in the input.


The .BIB macro from the macro file pca-bib.tmac introduces a paragraph that is a simple bibliographic reference, e.g.,

    .BIB landes_clock
    David S. Landes, \fIRevolutions in Time: Clocks and the
    Making of the Modern World\fP, Belknap Press, 1983.

If it is the nth such reference in the document, it is prefixed with “[n]” in the output. Furthermore, the label TAG:landes_clock is associated with n, using the cross-reference mechanism described earlier, and can be used to cite the reference. E.g.,

    For a history of the first portable device that, for better
    or worse, completely changed how we live, see