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.