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 makeinfo Pointer Creation), 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 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 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 makeinfo Pointer Creation).

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)info, 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 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 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 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.


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 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 Texinfo Mode, and makeinfo Pointer Creation.)

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.  This includes punctuation characters that are
escaped with a `@', such as @ and {.  For a few
rare cases when this is useful, Texinfo has limited support for using
@-commands in node names; see 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

* You cannot use parentheses in node names, because a node name such as
`(foo)bar' is interpreted by the Info readers as a node
`bar' in an Info file `foo'.

* 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 Include Files).  The Top node should contain a
short summary, copying permissions, and a master menu.  See The Top Node, 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. 

* On the other hand, 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.

* The `Next' node of the Top node should be the first chapter in your
document.


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

For concreteness, here is an example with explicit pointers (which you
can maintain automatically with the texinfo mode commands):

Or you can leave the pointers off entirely and let the tools implicitly
define them.  This is recommended.  Thus:

@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 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 @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 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 contain sectioning
commands at all.  For example, if you never intend the document to be
printed.  In those cases, you will need to explicitly specify the 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 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 goto-node in GNU Info.)


