texinfo: Node Line Requirements

@node

First Node

Writing a Node

Back to Software Index

6.1.3 '@node' Line Requirements
-------------------------------

Names used with '@node' have several requirements:

   * All the node names in a single Texinfo file must be unique.

     This means, for example, that if you end every chapter with a
     summary, you must name each summary node differently.  You cannot
     just call them all "Summary".  You may, however, duplicate the
     titles of chapters, sections, and the like.  Thus you can end each
     chapter with a section called "Summary", so long as the node names
     for those sections are all different.

   * The next/previous/up pointers on '@node' lines must be the names of
     nodes.  (It's recommended to leave out these explicit node pointer
     names, which automatically avoids any problem here; Note: makeinfo
     Pointer Creation.)

   * Node names can contain @-commands.  The output is generally the
     natural result of the command; for example, using '@TeX{}' in a
     node name results in the TeX logo being output, as it would be in
     normal text.  Cross references should use '@TeX{}' just as the node
     name does.

     For Info and HTML output, especially, it is necessary to expand
     commands to some sequence of characters; for instance, '@TeX{}'
     expands to the three letters 'TeX' in the Info node name.
     (However, cross references to the node should not take the
     "shortcut" of using 'TeX'; stick to the actual node name, commands
     and all.)

     Some commands do not make sense in node names; for instance,
     environments (e.g., '@quotation'), commands that read a whole line
     as their argument (e.g., '@sp'), and plenty of others.

     For the complete list of commands that are allowed, and their
     expansion for HTML identifiers and file names, Note: HTML Xref
     Command Expansion.  The expansions for Info are generally given
     with main the description of the command.

     Prior to the Texinfo 5 release in 2013, this feature was supported
     in an ad hoc way (the '--commands-in-node-names' option to
     'makeinfo').  Now it is part of the language.

   * Unfortunately, you cannot reliably use periods, commas, or colons
     within a node name; these confuse the Info reader.  Also, a node
     name may not start with a left parenthesis preceding a right
     parenthesis, as in '(not)allowed', since this syntax is used to
     specify an external manual.  (Perhaps these limitations will be
     removed some day.)

     If you insist on using these characters in node names, accepting
     the resulting substandard Info output, in order not to confuse the
     Texinfo processors, you must still escape those characters, by
     using either special insertions (Note: Inserting a Comma) or
     '@asis' (Note: @asis).  For example:

          @node foo@asis{::}bar

     As an example of avoiding the special characters, 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,
     but that is historical):

          unnumberedsec appendixsec heading

   * Case is significant in node names.

     Spaces before and after names on the '@node' line are ignored.
     Multiple whitespace characters "inside" a name are collapsed to a
     single space.  For example:

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

     all define the same node, namely 'foo bar'.  References to the node
     should all use that name, with no leading or trailing spaces a
     single internal space.