15.3 Contents and Short Table of Contents Customization

To begin with, the table of contents and short table of contents can be made to appear at different locations in the document.

By default, the customization variable CONTENTS_OUTPUT_LOCATION is set to ‘after_top’, specifying that the tables of contents are output at the end of the @top section, to have the main location for navigation in the whole document early on. This is in line with FORMAT_MENU set to ‘sectiontoc’ with sectioning command being used in HTML for navigation rather than menus.

If CONTENTS_OUTPUT_LOCATION is set to ‘inline’, the tables of content are output where the corresponding @-command, for example @contents, is set. This behavior is consistent with texi2dvi.

If CONTENTS_OUTPUT_LOCATION is set to ‘separate_element’, the tables of contents are output in separate elements, either at the end of the document if the output is unsplit or in separate files if not. This makes sense when menus are used for navigation with FORMAT_MENU set to ‘menu’.

If CONTENTS_OUTPUT_LOCATION is set to ‘after_title’ the tables of contents are merged into the title material, which in turn is not output by default; see HTML Title Page Customization.

Next, the following variables allow for some useful control of the formatting of table of contents and short table of contents:

BEFORE_TOC_LINES

Inserted before the table of contents text.

AFTER_TOC_LINES

Inserted after the table of contents text.

BEFORE_SHORT_TOC_LINES

Inserted before the short table of contents text.

AFTER_SHORT_TOC_LINES

Inserted after the short table of contents text.

Additional customization variables SHORT_TOC_LINK_TO_TOC and NUMBER_SECTIONS can be used to change the formatting of table of contents.

Finally, the following function reference provides even more control over the table of contents and short table of contents formatting reference:

Function Reference: $toc_result format_contents ($converter, $command_name, \%element, $filename)

$command_name is the @-command name without leading @, should be ‘contents’, ‘shortcontents’ or ‘summarycontents’. \%element is optional. It corresponds to the $command_name Texinfo tree element, but it is only set if format_contents is called from a Texinfo tree element conversion, and not as a special element body formatting. $filename is optional and should correspond to the filename where the formatting happens, for links.

In the default function, structuring information is used to format the table of contents (see Conversion General Information), and command_contents_href (see Other Links, Headings and Associated Information for Special Elements) and command_href (see Target Commands Links, Texts and Associated Commands) are used for links. If $filename is unset, the current file name is used, using $converter->get_info('current_filename').

Return formatted table of contents or short table of contents.

If contents are in a separate element unit (see Output Element Units), the default contents and shortcontents special element body formatting function calls format_contents (see Special Element Body Formatting Functions). Otherwise, format_contents is called in the conversion of heading @-command, in title page formatting, and in @contents conversion function, depending on the CONTENTS_OUTPUT_LOCATION value.