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

• 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 plain 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, see 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 can 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.)

  makeinfo warns about such problematic usage in node names, menu items, and cross-references. If you don’t want to see the warnings, you can set the customization variable INFO_SPECIAL_CHARS_WARNING to ‘0’ (see Other Customization Variables).

  Also, 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 (see Inserting a Comma) or @asis (see @asis). For example:

  @node foo@asis{::}bar
  

  As an example of avoiding the special characters, the following is a section title in this manual:

  @section @code{@@unnumbered}, @code{@@appendix}: ...
  

  But the corresponding node name lacks the commas and the subtitle:

  @node @unnumbered @appendix
  

• 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,
  @node  foo  bar ,
  

  all define the same node, namely ‘foo bar’. In menu entries, this is the name that should be used: no leading or trailing spaces, and a single internal space. (For cross-references, the node name used in the Texinfo sources is automatically normalized in this way.)

• 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; see makeinfo Pointer Creation.)