JezK
Edit File: Node-Line-Requirements.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Node Line Requirements (GNU Texinfo 6.8)</title> <meta name="description" content="Node Line Requirements (GNU Texinfo 6.8)"> <meta name="keywords" content="Node Line Requirements (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Nodes.html" rel="up" title="Nodes"> <link href="First-Node.html" rel="next" title="First Node"> <link href="Node-Names.html" rel="prev" title="Node Names"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="section" id="Node-Line-Requirements"> <div class="header"> <p> Next: <a href="First-Node.html" accesskey="n" rel="next">The First Node</a>, Previous: <a href="Node-Names.html" accesskey="p" rel="prev">Choosing Node Names</a>, Up: <a href="Nodes.html" accesskey="u" rel="up">Nodes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="g_t_0040node-Line-Requirements"></span><h3 class="section">3.3 <code>@node</code> Line Requirements</h3> <span id="index-Node-line-requirements"></span> <span id="index-Restrictions-on-node-names"></span> <p>Names used with <code>@node</code> have several requirements: </p> <ul> <li> <span id="index-Unique-node-names-requirement"></span> <span id="index-Node-names-must-be-unique"></span> All the node names in a single Texinfo file must be unique. <p>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. </p> </li><li> <span id="index-Commands-in-node-names"></span> <span id="index-at_0040_002dcommands-1"></span> Node names can contain @-commands. The output is generally the natural result of the command; for example, using <code>@TeX{}</code> in a node name results in the TeX logo being output, as it would be in normal text. Cross-references should use <code>@TeX{}</code> just as the node name does. <p>For Info and HTML output, especially, it is necessary to expand commands to some sequence of plain characters; for instance, <code>@TeX{}</code> expands to the three letters ‘<samp>TeX</samp>’ in the Info node name. However, cross-references to the node should not take the “shortcut” of using ‘<samp>TeX</samp>’; stick to the actual node name, commands and all. </p> <p>Some commands do not make sense in node names; for instance, environments (e.g., <code>@quotation</code>), commands that read a whole line as their argument (e.g., <code>@sp</code>), and plenty of others. </p> <p>For the complete list of commands that are allowed, and their expansion for HTML identifiers and file names, see <a href="HTML-Xref-Command-Expansion.html">HTML Cross-reference Command Expansion</a>. The expansions for Info are generally given with main the description of the command. </p> <p>Prior to the Texinfo 5 release in 2013, this feature was supported in an ad hoc way (the <samp>--commands-in-node-names</samp> option to <code>makeinfo</code>). Now it is part of the language. </p> </li><li> <span id="index-Colon-in-node-name"></span> <span id="index-Comma-in-node-name"></span> <span id="index-Parentheses-in-node-name"></span> <span id="index-Period-in-node-name"></span> <span id="index-Characters_002c-invalid-in-node-name"></span> <span id="index-Invalid-characters-in-node-names"></span> <span id="index-Node-names_002c-invalid-characters-in"></span> 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 <code>(not)allowed</code>, since this syntax is used to specify an external manual. (Perhaps these limitations will be removed some day.) <p><code>makeinfo</code> 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 <code>INFO_SPECIAL_CHARS_WARNING</code> to ‘<samp>0</samp>’ (see <a href="Other-Customization-Variables.html">Other Customization Variables</a>). </p> <p>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 <a href="Inserting-a-Comma.html">Inserting ‘,’ with <code>@comma{}</code></a>) or <code>@asis</code> (see <a href="_0040table.html#g_t_0040asis"><code>@asis</code></a>). For example: </p> <div class="example"> <pre class="example">@node foo@asis{::}bar </pre></div> <p>As an example of avoiding the special characters, the following is a section title in this manual: </p> <div class="example"> <pre class="example">@section @code{@@unnumbered}, @code{@@appendix}: Chapters with... </pre></div> <p>But the corresponding node name lacks the commas and the subtitle: </p> <div class="example"> <pre class="example">@node @code{@@unnumbered @@appendix} </pre></div> </li><li> <span id="index-Case-in-node-name"></span> Case is significant in node names. </li><li> <span id="index-White-space-in-node-name"></span> <span id="index-Spaces-in-node-name"></span> Spaces before and after names on the ‘<samp>@node</samp>’ line are ignored. Multiple whitespace characters “inside” a name are collapsed to a single space. For example: <div class="example"> <pre class="example">@node foo bar @node foo bar, @node foo bar , @node foo bar, @node foo bar , </pre></div> <p>all define the same node, namely ‘<samp>foo bar</samp>’. 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.) </p></li></ul> </div> <hr> <div class="header"> <p> Next: <a href="First-Node.html">The First Node</a>, Previous: <a href="Node-Names.html">Choosing Node Names</a>, Up: <a href="Nodes.html">Nodes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>