/usr/share/doc/texinfo/html/Node-Line-Requirements.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU Texinfo (version 6.5, 25 August 2017),
a documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
2010, 2011, 2012, 2013, 2014, 2015, 2016 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 the Front-Cover Texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation
License".

(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 6.4.90, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Node Line Requirements (GNU Texinfo 6.5)</title>

<meta name="description" content="Node Line Requirements (GNU Texinfo 6.5)">
<meta name="keywords" content="Node Line Requirements (GNU Texinfo 6.5)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Command-and-Variable-Index.html#Command-and-Variable-Index" rel="index" title="Command and Variable Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Nodes.html#Nodes" rel="up" title="Nodes">
<link href="First-Node.html#First-Node" rel="next" title="First Node">
<link href="Writing-a-Node.html#Writing-a-Node" rel="prev" title="Writing a Node">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {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}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Node-Line-Requirements"></a>
<div class="header">
<p>
Next: <a href="First-Node.html#First-Node" accesskey="n" rel="next">First Node</a>, Previous: <a href="Writing-a-Node.html#Writing-a-Node" accesskey="p" rel="prev">Writing a Node</a>, Up: <a href="Nodes.html#Nodes" accesskey="u" rel="up">Nodes</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="g_t_0040node-Line-Requirements"></a>
<h3 class="section">4.4 <code>@node</code> Line Requirements</h3>

<a name="index-Node-line-requirements"></a>
<a name="index-Restrictions-on-node-names"></a>

<p>Names used with <code>@node</code> have several requirements:
</p>
<ul>
<li> <a name="index-Unique-node-names-requirement"></a>
<a name="index-Node-names-must-be-unique"></a>
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 &ldquo;Summary&rdquo;.  You may, however, duplicate the titles of
chapters, sections, and the like.  Thus you can end each chapter with
a section called &ldquo;Summary&rdquo;, so long as the node names for those
sections are all different.
</p>
</li><li> <a name="index-Commands-in-node-names"></a>
<a name="index-_0040_002dcommands-in-node-names"></a>
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 &lsquo;<samp>TeX</samp>&rsquo; in the Info
node name.  However, cross-references to the node should not take the
&ldquo;shortcut&rdquo; of using &lsquo;<samp>TeX</samp>&rsquo;; 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-Xref-Command-Expansion">HTML Xref 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> <a name="index-Colon-in-node-name"></a>
<a name="index-Comma-in-node-name"></a>
<a name="index-Parentheses-in-node-name"></a>
<a name="index-Period-in-node-name"></a>
<a name="index-Characters_002c-invalid-in-node-name"></a>
<a name="index-Invalid-characters-in-node-names"></a>
<a name="index-Node-names_002c-invalid-characters-in"></a>
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&rsquo;t want to see the
warnings, you can set the customization variable
<code>INFO_SPECIAL_CHARS_WARNING</code> to &lsquo;<samp>0</samp>&rsquo; (see <a href="Other-Customization-Variables.html#Other-Customization-Variables">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-a-Comma">Inserting a Comma</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="smallexample">
<pre class="smallexample">@section @code{@@unnumbered}, @code{@@appendix}: ...
</pre></div>

<p>But the corresponding node name lacks the commas and the subtitle:
</p>
<div class="smallexample">
<pre class="smallexample">@node <code>@unnumbered @appendix</code>
</pre></div>

</li><li> <a name="index-Case-in-node-name"></a>
Case is significant in node names.

</li><li> <a name="index-White-space-in-node-name"></a>
<a name="index-Spaces-in-node-name"></a>
Spaces before and after names on the &lsquo;<samp>@node</samp>&rsquo; line are ignored.
Multiple whitespace characters &ldquo;inside&rdquo; 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 &lsquo;<samp>foo bar</samp>&rsquo;. 
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><li> The next/previous/up pointers on <code>@node</code> lines must be the names
of nodes.  (It&rsquo;s recommended to leave out these explicit node pointer
names, which automatically avoids any problem here; see <a href="makeinfo-Pointer-Creation.html#makeinfo-Pointer-Creation"><code>makeinfo</code> Pointer Creation</a>.)
</li></ul>


<hr>
<div class="header">
<p>
Next: <a href="First-Node.html#First-Node" accesskey="n" rel="next">First Node</a>, Previous: <a href="Writing-a-Node.html#Writing-a-Node" accesskey="p" rel="prev">Writing a Node</a>, Up: <a href="Nodes.html#Nodes" accesskey="u" rel="up">Nodes</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html#Command-and-Variable-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
texinfo-doc-nonfree 6.5.0-1 / usr / share / doc / texinfo / html / Node-Line-Requirements.html
