Nodes

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

Info output and printed output.
• Node Menu Illustration: A diagram, and sample nodes and menus.
• node: How to write a node, in detail.
• makeinfo Pointer Creation: How to create node pointers with makeinfo.

The node and menu commands and the chapter structuring commands are 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, most Texinfo files are written such that the structure for the Info output corresponds to the structure for the printed output. It is not convenient 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.

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.

Note that 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

Write the beginning of the node for Chapter 2 like 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".

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 may follow a chapter-level node, and a subsection-level node may follow a section-level node. `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 section 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

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 four arguments, separated by commas, on the rest of the same line. These arguments are the name of the node, and the names of the `Next', `Previous', and `Up' pointers, in that order. You may insert spaces before each pointer 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 Types of Structuring Command.)

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 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 its related commands; see section Cross References.)

• 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.

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 The First Node, for information on how to write the first node of a Texinfo file.

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 Using Texinfo Mode, and section 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 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.

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

@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.
• You cannot use any of the Texinfo @-commands in a node name; @-commands confuse Info. 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
  

• You cannot use 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.

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 (which must be named `top' or `Top') should have as its `Up' and `Previous' nodes 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 Info. For example, the @node Top line of this manual looks like this:

@node Top, Overview, (dir), (dir)

(You may use the Texinfo updating commands or the makeinfo utility to insert these `Next' and `(dir)' pointers automatically.)

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

The `Top' node contains the main or master menu for the document.

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.

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 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 @titlepage.)

Creating Pointers with makeinfo

The makeinfo program has a feature for automatically creating node pointers for a hierarchically organized file that lacks them.

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. You cannot write a comment line after a node line; the section line must follow it immediately.

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.

This node pointer insertion feature in makeinfo is an alternative to the menu and pointer creation and update commands in Texinfo mode. (See section Updating Nodes and Menus.) It is especially helpful to people who do not use GNU Emacs for writing Texinfo documents.