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_troffcl

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

    Extending troff using Common Lisp, \*[TAG:sec_troffcl]

In the HTML output, the string \*[TAG:sec_troffcl] furthermore is a link to where .TAG sec_troffcl 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.

The troff2page aspect of pca-toc.tmac uses .TAG. 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.

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