Table of contents: How do I generate a table of contents
What steps do authors need to take to produce a suitable table of contents for printed material? Are there any traps for the unwary?
The Scholarly King, dictionary at hand
Wikipublisher generates a table of contents using the document’s hierarchical structure to determine the entries. In particular, when typesetting a trail, the structure of the trail list defines the document hierarchy:
- (:typeset:) generates a report-style output and each level 1 list item is a section; toc is on by default
- (:typeset-trail toc=on:) generates an article-style output and each level 1 list item is a section; toc is off by default
- (:typeset-book:) generates a book-style output, and each level 1 list item is a chapter; toc is on by default
When typesetting a single page, authors have a couple of choices:
- use a (:toc:) directive to generate a 2-level HTML table of contents; in the PDF the links become page number references
- use a (:typeset-page toc=on:) directive for a print-only table of contents
Wikipublisher uses the headings on a page to infer a structural hierarchy. The HTML heading markup is absolute — <h3> is always a third level heading. On the other hand, Wikipublisher heading markup is relative — if <h3> is the first heading on the page, it becomes a section, but if it follows <h2> then <h2> becomes a section and <h3> becomes a subsection. If the page is typeset as part of a trail, headings are interpreted relative to the position of the page in the trail hierarchy. So if the page is a section, the first heading becomes a subsection.
The structure of a Wikipublisher document is chapter (book only), section, subsection, subsubsection, paragraph, subparagraph. It currently handles 3 levels of heading per page. If an author uses 4 or more heading levels, the lower level ones are formatted as headings, but do not form part of the document’s structural hierarchy. By combining trail lists and headings, authors can create hierarchies 5 (reports and articles) or 6 (books) levels deep.
In practice, this means Wikipublisher smoothes out markup differences — when you typeset a trail, the structure will be regular, even if different authors use different heading conventions.
Category: navigation aid
