5.1 Output Element Units

We will call the main unit of output documents a document unit, or a Texinfo tree element unit. An element unit’s association with output files is determined by the split options (see Splitting Output in Texinfo). This section describes precisely how these output units work, with details for customization.

The output elements are:

Normal document units

These are normal sections and nodes. Usually a node is associated with a following sectioning command, while a sectioning command is associated with a previous node; they both together make up the element unit. Either the node or the sectioning command is considered to be the main element component, depending on the values of the customization variables USE_NODES (see HTML Customization Variables in Texinfo).

For example, when generating Info, the nodes are the units; when generating HTML, either case may happen (see Two Paths in Texinfo).

Top element

The top element is the highest element unit in the document structure. If the document has an @top section (see @top Command in Texinfo), it is the element associated with that section; otherwise, it is the element associated with the document’s @node Top (see The Top Node in Texinfo). If there is no @node Top, the first element in the document is the top element. The Top element is also a normal element.

Miscellaneous elements

The remaining element units are associated with different files if the document is split, and also if MONOLITHIC is not set. There are four such miscellaneous elements, also called special elements:

  1. Table of contents
  2. Short table of contents, also called Overview
  3. Footnotes page
  4. About page

More details:

  • The Table of contents should only be formatted if @contents is present in the document.
  • Similarly the Short table of contents should only appear if @shortcontents or @summarycontents is present.
  • The customization variables contents and shortcontents may be set to trigger the output of the respective elements.
  • If CONTENTS_OUTPUT_LOCATION is set to ‘separate_element’, the Table of contents and Short table of contents elements are separate (see Contents and Short Table of Contents Customization). Otherwise the Table of contents and Short table of contents elements are directly included within the document, at locations depending on the specific CONTENTS_OUTPUT_LOCATION value.
  • When generating HTML, the Footnotes page should only be present if the footnotes appear on a separate page (see Footnote Styles in Texinfo). However, a footnote element is present if the document is not split.
  • The About page shouldn’t be present for documents consisting of only one sectioning element, or for monolithic documents without navigation information, or if DO_ABOUT is not set.

It is common not to have anything but normal element units, especially in case of monolithic output.

The main component of elements is sections if USE_NODES is 0; conversely, the main component is nodes if USE_NODES is set.

When sections are the main components of element units, “isolated” nodes not directly associated with a sectioning command are associated with the following sectioning command, while sectioning commands without nodes constitute element units. Conversely, when nodes are the main components of elements, isolated sections not associated with nodes are associated with the previous node, and isolated nodes are element units.