3.6 Texinfo Document Structure

Nodes can contain menus, which contain the names of child nodes 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 the Info output.

In addition, nodes contain node pointers that name other nodes. The ‘Next’ and ‘Previous’ pointers link nodes at the same sectioning level into a chain. As you might imagine, the ‘Next’ pointer links to the next node, and the ‘Previous’ pointer links to the previous node. In general, ‘Next’ and ‘Previous’ refer to nodes at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may be at a lower level—a section-level node most often follows a chapter-level node, for example. 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 the parent chapter. Each child node records the parent node name as its ‘Up’ pointer.

Since the ‘Top’ node is the only node at that level, ‘Next’ refers to the first following node, which is almost always a chapter or chapter-level node. This is an exception to the rule of ‘Next’ being at the same hierarchical level.

The Info and HTML output for each node includes links to the ‘Next’, ‘Previous’, and ‘Up’ nodes. The HTML also uses the accesskey attribute with the values ‘n’, ‘p’, and ‘u’ respectively. This allows people using web browsers to follow the navigation using (typically) M-letter, e.g., M-n for the ‘Next’ node, from anywhere within the node. Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like provide structure for printed books. The two structures are theoretically distinct; in practice, however, the tree structure of printed books is essentially always used for the node and menu structure also, as this leads to a document which is easy to follow.

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.

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 different from the conventional structure. To the best of our knowledge, however, all the Texinfo manuals currently in general use do follow the conventional parallel structure.