groff: ms TOC
4.3.6.4 Creating a table of contents
....................................
The facilities in the 'ms' macro package for creating a table of
contents are semi-automated at best. Assuming that you want the table
of contents to consist of the document's headings, you need to repeat
those headings wrapped in 'XS' and 'XE' macros.
-- Macro: .XS [page]
-- Macro: .XA [page]
-- Macro: .XE
These macros define a table of contents or an individual entry in
the table of contents, depending on their use. The macros are very
simple; they cannot indent a heading based on its level. The
easiest way to work around this is to add tabs to the table of
contents string. The following is an example:
.NH 1
Introduction
.XS
Introduction
.XE
.LP
...
.CW
.NH 2
Methodology
.XS
Methodology
.XE
.LP
...
You can manually create a table of contents by beginning with the
'XS' macro for the first entry, specifying the page number for that
entry as the argument to 'XS'. Add subsequent entries using the
'XA' macro, specifying the page number for that entry as the
argument to 'XA'. The following is an example:
.XS 1
Introduction
.XA 2
A Brief History of the Universe
.XA 729
Details of Galactic Formation
...
.XE
-- Macro: .TC [no]
Prints the table of contents on a new page, setting the page number
to *i* (Roman lowercase numeral one). You should usually place
this macro at the end of the file, since 'groff' is a single-pass
formatter and can only print what has been collected up to the
point that the 'TC' macro appears.
The optional argument 'no' suppresses printing the title specified
by the string register 'TOC'.
-- Macro: .PX [no]
Prints the table of contents on a new page, using the current page
numbering sequence. Use this macro to print a manually generated
table of contents at the beginning of your document.
The optional argument 'no' suppresses printing the title specified
by the string register 'TOC'.
The 'Groff and Friends HOWTO' includes a 'sed' script that
automatically inserts 'XS' and 'XE' macro entries after each heading in
a document.
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.