texinfo: Texinfo Document Structure

Overview

Info Files

Adding Output Formats

Back to Software Index

1.5 Texinfo Document Structure
==============================

Texinfo documents most usefully have a double structure, reflecting the
double purposes of printed and online output.  For printed output (DVI,
PDF, ...), with physical pages, there are chapters, sections,
subsections, etc.  For online output (Info, HTML, ...), with interactive
navigation and no physical pages, there are so-called "nodes".

  Typically, the sectioning structure and the node structure are
completely parallel, with one node for each chapter, section, etc., and
with the nodes following the same hierarchical arrangement as the
sectioning.  Thus, if a node is at the logical level of a chapter, its
child nodes are at the level of sections; similarly, the child nodes of
sections are at the level of subsections.

  Each "node" has a name, and contains the discussion of one topic.
Along with the text for the user to read, each node also has pointers to
other nodes, identified in turn by their own names.  Info readers
display one node at a time, and provide commands for the user to move to
related nodes.  The HTML output can be similarly navigated.

  The names of child nodes are listed in a "menu" within the parent
node; for example, a node corresponding to a chapter would have a menu
of the sections in that chapter.  The menus allow the user to move to
the child nodes in a natural way in the online output.

  In addition, nodes at the same level are formed into a chain with
'Next' and 'Previous' pointers.  As you might imagine, the 'Next'
pointer links to the next node (section), and the 'Previous' pointer
links to the previous node (section).  Thus, for example, all the nodes
that are at the level of sections within a chapter are linked together,
and the order in this chain is the same as the order of the children in
the menu of parent chapter.  Each child node records the parent node
name as its 'Up' pointer.  The last child has no 'Next' pointer, and the
first child has the parent both as its 'Previous' and as its 'Up'
pointer.

  In addition to menus and 'Next', 'Previous', and 'Up' pointers,
Texinfo provides pointers of another kind for cross references, that can
be sprinkled throughout the text.  This is usually the best way to
represent links that do not fit a hierarchical structure.

  Although it is technically possible to create Texinfo documents with
only one structure or the other, or for the two structures not to be
parallel, or for either the sectioning or node structure to be
abnormally formed, etc., this is _not at all recommended_.  To the best
of our knowledge, all the Texinfo manuals currently in general use do
follow the conventional parallel structure.