Go to the first, previous, next, last section, table of contents.

6. Nodes

Nodes are the primary segments of a Texinfo file. They do not 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.

Two Paths: Different commands to structure Info output and printed output.
Node Menu Illustration: A diagram, and sample nodes and menus.
node: Creating nodes, in detail.
makeinfo Pointer Creation: Letting makeinfo determine node pointers.
anchor: Defining arbitrary cross-reference targets.

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 6.4 Creating Pointers with makeinfo), but the pointer relationships still obtain.

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 7. 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 section 8. 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 create 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. 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 6.4 Creating Pointers with makeinfo).

You may insert spaces before each name if you wish; the spaces are ignored. You must write the name of the node and the names of the `Next', `Previous', and `Up' pointers all on the same line. Otherwise, the formatters fail. (See Info file `info', node `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 5.2 Structuring Command Types.)

Please note: The GNU Emacs Texinfo mode updating commands work only with Texinfo files in which @node lines are followed by chapter structuring lines. See section 2.5.2 Updating Requirements.

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 section 8. Cross References.)

Node Names: How to choose node and pointer names.
Writing a Node: How to write an @node line.
Node Line Tips: Keep names short.
Node Line Requirements: Keep names unique, without @-commands.
First Node: How to write a `Top' node.
makeinfo top command: How to use the @top command.
Top Node Summary: Write a brief description for readers.

6.3.1 Choosing Node and Pointer Names

The name of a node identifies the node. The pointers enable you to reach other nodes and consist 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 that 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 6.3.5 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 printed 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 GNU Emacs, 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 2. Using Texinfo Mode, and section 6.4 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

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 used in node names generally confuse Info, so you should avoid them. For a few rare cases when this is useful, Texinfo has limited support for using @-commands in node names; see section 20.1.4 Pointer Validation. Thus, the beginning of the section called @chapter looks like this:
```
@node  chapter, unnumbered & appendix, makeinfo top, Structuring
@comment  node-name,  next,  previous,  up
@section @code{@@chapter}
@findex chapter
```
Unfortunately, you cannot use periods, commas, colons or apostrophes within a node name; these confuse TeX or the Info formatters. For example, the following is a section title:
```
@code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
```
The corresponding node name is:
```
unnumberedsec appendixsec heading
```
Case is significant.

6.3.5 The First Node

The first node of a Texinfo file is the Top node, except in an included file (see section E. Include Files). The Top node contains the main or master menu for the document, and a short summary of the document (see section 6.3.7 The `Top' Node Summary).

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. If the file is to be installed directly in the Info directory file, 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. For example, the @node Top line of this manual looks like this:

@node Top, Copying, , (dir)

(You can use the Texinfo updating commands or the makeinfo utility to insert these pointers automatically.)

Do not define the `Previous' node of the Top node to be `(dir)', as it causes confusing behavior for users: if you are in the Top node and hits DEL to go backwards, you wind up in the middle of the some other entry in the `dir' file, which has nothing to do with what you were reading.

See section 20.2 Installing an Info File, for more information about installing an Info file in the `info' directory.

6.3.6 The `@top` Sectioning Command

A special sectioning command, @top, has been created for use 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.

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.

6.3.7 The `Top' Node Summary

You can help readers by writing a summary in the `Top' node, after the @top line, before the main or master menu. The summary should briefly describe the document. In Info, this summary will appear just before the master menu. In a printed manual, this summary will appear on a page of its own.

If you do not want the summary to appear on a page of its own in a printed manual, you can enclose the whole of the `Top' node, including the @node Top line and the @top sectioning command line or other sectioning command line between @ifinfo and @end ifinfo. This prevents any of the text from appearing in the printed output. (see section 16. Conditionally Visible Text). You can repeat the brief description from the `Top' node within @iftex ... @end iftex at the beginning of the first chapter, for those who read the printed manual. This saves paper and may look neater.

You should write the version number of the program to which the manual applies in the summary. This helps the reader keep track of which manual is for which version of the program. If the manual changes more frequently than the program or is independent of it, you should also include an edition number for the manual. (The title page should also contain this information: see section 3.5.1 @titlepage.)

6.4 Creating Pointers with `makeinfo`

The makeinfo program has a feature for automatically defining node pointers for a hierarchically organized file.

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 5.3 @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.

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

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 8. 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. Spaces are always 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 section `goto-node' in GNU Info.)

Go to the first, previous, next, last section, table of contents.