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:
$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.