6. Nodes

Nodes are the primary segments of a Texinfo file. They do not in and of themselves impose a hierarchical or any other kind of structure on a file. Nodes contain node pointers that name other nodes, and can contain menus which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu.

Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like, provide structure for printed books.

Because node names are used in cross-references, it is not desirable to casually change them. Such name changes invalidate references from other manuals, from mail archives, and so on.

6.1 Two Paths

The node and menu commands and the chapter structuring commands are technically independent of each other:

• In Info, node and menu commands provide structure. The chapter structuring commands generate headings with different kinds of underlining—asterisks for chapters, hyphens for sections, and so on; they do nothing else.
• In TeX, the chapter structuring commands generate chapter and section numbers and tables of contents. The node and menu commands provide information for cross references; they do nothing else.

You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a different structure than its printed output. However, virtually all Texinfo files are written such that the structure for the Info output corresponds to the structure for the printed output. It is neither convenient nor understandable to the reader to do otherwise.

Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.

6.2 Node and Menu Illustration

Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.

The “root” is at the top of the diagram and the “leaves” are at the bottom. This is how such a diagram is drawn conventionally; it illustrates an upside-down tree. For this reason, the root node is called the ‘Top’ node, and ‘Up’ node pointers carry you closer to the root.

                         Top
                          |
        -------------------------------------
       |                  |                  |
    Chapter 1          Chapter 2          Chapter 3
       |                  |                  |
    --------           --------           --------
   |        |         |        |         |        |
Section  Section   Section  Section   Section  Section
  1.1      1.2       2.1      2.2       3.1      3.2

The fully-written command to start Chapter 2 would be this:

@node     Chapter 2,  Chapter 3, Chapter 1, Top
@comment  node-name,  next,      previous,  up

This @node line says that the name of this node is “Chapter 2”, the name of the ‘Next’ node is “Chapter 3”, the name of the ‘Previous’ node is “Chapter 1”, and the name of the ‘Up’ node is “Top”. You can omit writing out these node names if your document is hierarchically organized (see section Creating Pointers with makeinfo), but the pointer relationships still obtain.

Note: Please Note: ‘Next’ refers to the next node 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. ‘Next’ and ‘Previous’ refer to nodes at the same hierarchical level. (The ‘Top’ node contains the exception to this rule. 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.)

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 2. (See section Menus.) You would write the menu just before the beginning of Section 2.1, like this:

   @menu
   * Sect. 2.1::    Description of this section.
   * Sect. 2.2::
   @end menu

Write the node for Sect. 2.1 like this:

   @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
   @comment  node-name, next,      previous,  up

In Info format, the ‘Next’ and ‘Previous’ pointers of a node usually lead to other nodes at the same level—from chapter to chapter or from section to section (sometimes, as shown, the ‘Previous’ pointer points up); an ‘Up’ pointer usually leads to a node at the level above (closer to the ‘Top’ node); and a ‘Menu’ leads to nodes at a level below (closer to ‘leaves’). (A cross reference can point to a node at any level; see Cross References.)

Usually, an @node command and a chapter structuring command are used in sequence, along with indexing commands. (You may follow the @node line with a comment line that reminds you which pointer is which.)

Here is the beginning of the chapter in this manual called “Ending a Texinfo File”. This shows an @node line followed by a comment line, an @chapter line, and then by indexing lines.

@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

6.3 The @node Command

A node is a segment of text that begins at an @node command and continues until the next @node command. The definition of node is different from that for chapter or section. A chapter may contain sections and a section may contain subsections; but a node cannot contain subnodes; the text of a node continues only until the next @node command in the file. A node usually contains only one chapter structuring command, the one that follows the @node line. On the other hand, in printed output nodes are used only for cross references, so a chapter or section may contain any number of nodes. Indeed, a chapter usually contains several nodes, one for each section, subsection, and subsubsection.

To specify a node, write an @node command at the beginning of a line, and follow it with up to four arguments, separated by commas, on the rest of the same line. The first argument is required; it is the name of this node (for details of node names, see section @node Line Requirements). The subsequent arguments are the names of the ‘Next’, ‘Previous’, and ‘Up’ pointers, in that order, and may be omitted if your Texinfo document is hierarchically organized (see section Creating Pointers with makeinfo).

Whether the node pointers are specified implicitly or explicitly, the HTML output from makeinfo 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 nagivation using (typically) M-letter, e.g., M-n for the ‘Next’ node, from anywhere within the node.

You may insert spaces before each name on the @node line if you wish; the spaces are ignored. You must write the name of the node and (if present) the names of the ‘Next’, ‘Previous’, and ‘Up’ pointers all on the same line. Otherwise, the formatters fail. (See info: (info)Top, for more information about nodes in Info.)

Usually, you write one of the chapter-structuring command lines immediately after an @node line—for example, an @section or @subsection line. (See section Structuring Command Types.)

TeX uses @node lines to identify the names to use for cross references. For this reason, you must write @node lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the end of this sentence, are made with @xref and related commands; see Cross References.)

6.3.1 Choosing Node and Pointer Names

The name of a node identifies the node (for details of node names, see section @node Line Requirements). The pointers enable you to reach other nodes and consist simply of the names of those nodes.

Normally, a node’s ‘Up’ pointer contains the name of the node whose menu mentions that node. The node’s ‘Next’ pointer contains the name of the node that follows the present node in that menu and its ‘Previous’ pointer contains the name of the node that precedes it in that menu. When a node’s ‘Previous’ node is the same as its ‘Up’ node, both node pointers name the same node.

Usually, the first node of a Texinfo file is the ‘Top’ node, and its ‘Up’ and ‘Previous’ pointers point to the ‘dir’ file, which contains the main menu for all of Info.

The ‘Top’ node itself contains the main or master menu for the manual. Also, it is helpful to include a brief description of the manual in the ‘Top’ node. See section The First Node, for information on how to write the first node of a Texinfo file.

Even when you explicitly specify all pointers, that does not mean you can write the nodes in the Texinfo source file in an arbitrary order! Because TeX processes the file sequentially, irrespective of node pointers, you must write the nodes in the order you wish them to appear in the output.

6.3.2 How to Write an @node Line

The easiest way to write an @node line is to write @node at the beginning of a line and then the name of the node, like this:

@node node-name

If you are using XEmacs, you can use the update node commands provided by Texinfo mode to insert the names of the pointers; or you can leave the pointers out of the Texinfo file and let makeinfo insert node pointers into the Info file it creates. (See section Using Texinfo Mode, and Creating Pointers with makeinfo.)

Alternatively, you can insert the ‘Next’, ‘Previous’, and ‘Up’ pointers yourself. If you do this, you may find it helpful to use the Texinfo mode keyboard command C-c C-c n. This command inserts ‘@node’ and a comment line listing the names of the pointers in their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.

The template for a fully-written-out node line with ‘Next’, ‘Previous’, and ‘Up’ pointers looks like this:

@node node-name, next, previous, up

The node-name argument must be present, but the others are optional. If you wish to specify some but not others, just insert commas as needed, as in: ‘@node mynode,,,uppernode’. However, we recommend leaving off all the pointers and letting makeinfo determine them, as described above.

If you wish, you can ignore @node lines altogether in your first draft and then use the texinfo-insert-node-lines command to create @node lines for you. However, we do not recommend this practice. It is better to name the node itself at the same time that you write a segment so you can easily make cross references. A large number of cross references are an especially important feature of a good Info file.

After you have inserted an @node line, you should immediately write an @-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it much easier for people to find the node.

6.3.3 @node Line Tips

Here are three suggestions:

• Try to pick node names that are informative but short.

  In the Info file, the file name, node name, and pointer names are all inserted on one line, which may run into the right edge of the window. (This does not cause a problem with Info, but is ugly.)

• Try to pick node names that differ from each other near the beginnings of their names. This way, it is easy to use automatic name completion in Info.
• By convention, node names are capitalized just as they would be for section or chapter titles—initial and significant words are capitalized; others are not.

6.3.4 @node Line Requirements

Here are several requirements for @node lines:

• All the node names for a single Info file must be unique.

  Duplicates confuse the Info movement commands. This means, for example, that if you end every chapter with a summary, you must name each summary node differently. You cannot just call each one “Summary”. You may, however, duplicate the titles of chapters, sections, and the like. Thus you can end each chapter in a book with a section called “Summary”, so long as the node names for those sections are all different.

• A pointer name must be the name of a node.

  The node to which a pointer points may come before or after the node containing the pointer.

• @-commands in node names are not allowed. This includes punctuation characters that are escaped with a ‘@’, such as @ and {, and accent commands such as ‘@'’. (For a few cases when this is useful, Texinfo has limited support for using @-commands in node names; see Pointer Validation.) Perhaps this limitation will be removed some day.
• Unfortunately, you cannot use periods, commas, colons or parentheses within a node name; these confuse the Texinfo processors. Perhaps this limitation will be removed some day, too.

  For example, the following is a section title in this manual:

  @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}

  But the corresponding node name lacks the commas and the @’s:

  unnumberedsec appendixsec heading

• Case is significant in node names.

  Spaces before and after names on the ‘@node’ line are ignored, but spaces “inside” a name are significant. For example:

  @node foo bar, @node foo bar , @node foo bar ,

  all define the same node, ‘foo bar’. References to the node should all use that name, without the leading or trailing spaces, but with the internal spaces.

6.3.5 The First Node

The first node of a Texinfo file is the Top node, except in an included file (see section Include Files). The Top node should contain a short summary, copying permissions, and a master menu. See section The ‘Top’ Node and Master Menu, for more information on the Top node contents and examples.

Here is a description of the node pointers to be used in the Top node:

• The Top node (which must be named ‘top’ or ‘Top’) should have as its ‘Up’ node the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses.

  Usually, all Info files are installed in the same Info directory tree; in this case, use ‘(dir)’ as the parent of the Top node; this is short for ‘(dir)top’, and specifies the Top node in the ‘dir’ file, which contains the main menu for the Info system as a whole.

• The ‘Prev’ node of the Top node should also be your ‘(dir)’ file.
• The ‘Next’ node of the Top node should be the first chapter in your document.

See section Installing an Info File, for more information about installing an Info file in the ‘info’ directory.

It is usually best to leave the pointers off entirely and let the tools implicitly define them, with this simple result:

@node Top

6.3.6 The @top Sectioning Command

A special sectioning command, @top should be used with the @node Top line. The @top sectioning command tells makeinfo that it marks the ‘Top’ node in the file. It provides the information that makeinfo needs to insert node pointers automatically. Write the @top command at the beginning of the line immediately following the @node Top line. Write the title on the remaining part of the same line as the @top command.

In Info, the @top sectioning command causes the title to appear on a line by itself, with a line of asterisks inserted underneath, as other sectioning commands do.

In TeX and texinfo-format-buffer, the @top sectioning command is merely a synonym for @unnumbered. Neither of these formatters require an @top command, and do nothing special with it. You can use @chapter or @unnumbered after the @node Top line when you use these formatters. Also, you can use @chapter or @unnumbered when you use the Texinfo updating commands to create or update pointers and menus.

Thus, in practice, a Top node starts like this:

@node Top
@top Your Manual Title

6.4 Creating Pointers with makeinfo

The makeinfo program has a feature for automatically determining node pointers for a hierarchically organized document. We highly recommend using it.

When you take advantage of this feature, you do not need to write the ‘Next’, ‘Previous’, and ‘Up’ pointers after the name of a node. However, you must write a sectioning command, such as @chapter or @section, on the line immediately following each truncated @node line (except that comment lines may intervene).

In addition, you must follow the ‘Top’ @node line with a line beginning with @top to mark the ‘Top’ node in the file. See section @top.

Finally, you must write the name of each node (except for the ‘Top’ node) in a menu that is one or more hierarchical levels above the node’s hierarchical level.

If you use a detailed menu in your master menu (see section Parts of a Master Menu), mark it with the @detailmenu @dots{} @end detailmenu environment, or makeinfo will get confused, typically about the last and/or first node in the document.

This implicit node pointer creation feature in makeinfo relieves you from the need to update menus and pointers manually or with Texinfo mode commands. (See section Updating Nodes and Menus.)

In most cases, you will want to take advantage of this feature and not redundantly specify node pointers. However, Texinfo documents are not required to be organized hierarchically or in fact to contain sectioning commands at all (for example, if you never intend the document to be printed). The special procedure for handling the short text before a menu (see section Menus) also disables this feature, for that group of nodes. In those cases, you will need to explicitly specify all pointers.

6.5 @anchor: Defining Arbitrary Cross-reference Targets

An anchor is a position in your document, labeled so that cross-references can refer to it, just as they can to nodes. You create an anchor with the @anchor command, and give the label as a normal brace-delimited argument. For example:

This marks the @anchor{x-spot}spot.
…
@xref{x-spot,,the spot}.

produces:

This marks the spot.
…
See [the spot], page 1.

As you can see, the @anchor command itself produces no output. This example defines an anchor ‘x-spot’ just before the word ‘spot’. You can refer to it later with an @xref or other cross-reference command, as shown. See section Cross References, for details on the cross-reference commands.

It is best to put @anchor commands just before the position you wish to refer to; that way, the reader’s eye is led on to the correct text when they jump to the anchor. You can put the @anchor command on a line by itself if that helps readability of the source. Whitespace (including newlines) is ignored after @anchor.

Anchor names and node names may not conflict. Anchors and nodes are given similar treatment in some ways; for example, the goto-node command in standalone Info takes either an anchor name or a node name as an argument. (See (info-stnd)goto-node section ‘goto-node’ in GNU Info.)

Also like node names, anchor names cannot include some characters (see section @node Line Requirements).

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.