texinfo: Contents

Beginning a File

The Top Node

Titlepage & Copyright Page

Back to Software Index

3.5 Generating a Table of Contents
==================================

The '@chapter', '@section', and other structuring commands (Note:
Chapter Structuring) supply the information to make up a table of
contents, but they do not cause an actual table to appear in the manual.
To do this, you must use the '@contents' and/or '@summarycontents'
command(s).

'@contents'
     Generates a table of contents in a printed manual, including all
     chapters, sections, subsections, etc., as well as appendices and
     unnumbered chapters.  Headings generated by '@majorheading',
     '@chapheading', and the other '@...heading' commands do not appear
     in the table of contents (Note: Structuring Command Types).

'@shortcontents'
'@summarycontents'
     ('@summarycontents' is a synonym for '@shortcontents'.)

     Generates a short or summary table of contents that lists only the
     chapters, appendices, and unnumbered chapters.  Sections,
     subsections and subsubsections are omitted.  Only a long manual
     needs a short table of contents in addition to the full table of
     contents.

  Both contents commands should be written on a line by themselves, and
placed near the beginning of the file, after the '@end titlepage' (Note:
@titlepage), before any sectioning command.  The contents commands
automatically generate a chapter-like heading at the top of the first
table of contents page, so don't include any sectioning command such as
'@unnumbered' before them.

  Since an Info file uses menus instead of tables of contents, the Info
formatting commands ignore the contents commands.  But the contents are
included in plain text output (generated by 'makeinfo --plaintext') and
in other output formats, such as HTML.

  When 'makeinfo' writes a short table of contents while producing HTML
output, the links in the short table of contents point to corresponding
entries in the full table of contents rather than the text of the
document.  The links in the full table of contents point to the main
text of the document.

  In the past, the contents commands were sometimes placed at the end of
the file, after any indices and just before the '@bye', but we no longer
recommend this.

  However, since many existing Texinfo documents still do have the
'@contents' at the end of the manual, if you are a user printing a
manual, you may wish to force the contents to be printed after the title
page.  You can do this by specifying '@setcontentsaftertitlepage' and/or
'@setshortcontentsaftertitlepage'.  The first prints only the main
contents after the '@end titlepage'; the second prints both the short
contents and the main contents.  In either case, any subsequent
'@contents' or '@shortcontents' is ignored.

  You need to include the '@set...contentsaftertitlepage' commands early
in the document (just after '@setfilename', for example).  We recommend
using 'texi2dvi' (Note: Format with texi2dvi) to specify this without
altering the source file at all.  For example:

     texi2dvi --texinfo=@setcontentsaftertitlepage foo.texi

  An alternative invocation, using 'texi2any':

     texi2any --dvi --Xopt --texinfo=@setcontentsaftertitlepage foo.texi