5. Making an index

The supplied macro file pca-ix.tmac creates a sorted index, with the aid of the external program MakeIndex. MakeIndex is included with TeX distributions, but you can also obtain just the MakeIndex distribution.

Note that the indexes created by groff and Troff2page are necessarily different, because the respective paginations are different. In addition, the index generated for Troff2page has the additional feature of hyperlinking to the appropriate locations in the body text.

The call

    .IX item

marks the text “item” as an indexable item. The metacharacters @, !, ", and | can be used to respectively specify (a) alternate alphabetization, (b) subitems, (c) literal metacharacters, and (d) encapsulation of the page number.


    .IX m@-m, groff option

identifies an index entry for “-m, groff option” but alphabetizes it as though it were “m” rather than something that starts with a hyphen.

    .IX groff!macro packages

makes “macro packages” an indented index subentry under “groff”. Up to two !s may be used.

    .IX groff!macro packages!ms

produces “ms” as a subsubentry under “macro packages” under “groff”.

    .IX troff|see groff

has the index entry for “troff” point to “groff” rather than have a page number of its own.

If any of the metacharacters need to appear in the index entry as themselves, precede them with ".

    .IX set"!car

creates an index entry for “set!car” rather than creating a subentry “car” under “set"”.

Please see the MakeIndex documentation for all the details. Essentially, the syntax for entering index entries is the same as for LaTeX, except that in groff we use “.IX item” where in LaTeX one would use “\index{item}”.

pca-ix.tmac will call MakeIndex to create a sorted index in the auxiliary file \*[AUXF].ind, which can be slurped back into the input document:

    .so \*[AUXF].ind

Adding a section header on top is up to you.