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.)
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 troff 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 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.”