Prev: sectiontype-and-ref
Up: Sectioning
Top: Top
0.2.2.4. GNU Info node specifications with `\section<n>'
[APRIL91: Don't overlook the new ideas in
section See revised-sectioning.]
When making an on-line Info document from a literate program, the text
between two sectioning commands is turned into an Info node.
Moreover, the sectioning commands are used to determine how the nodes
should be linked together -- almost always in the hierarchical structure
implied by the sectioning. However, you can tweak the process as much
as you wish (almost no-one ever wishes...).
Each `\section<n>' command may have an optional "node specification",
with which you may specify the name of the Info node and how it should
be linked to other nodes. For common practice, I
recommend giving a (unique) node name and enjoying the default links;
for example:
\section[Foo-Sem]{Foo Semantics}
Besides serving as the node name, `Foo-Sem' will also be a LaTeX
`\label' and may be `\ref''d or `\pageref''d: for example,
you could say, "The semantics are given in
section~\ref{Foo_Sem}". (This is more likely to work than
introducing a `\label' of your own and `\ref''ing that.)
Node names must not contain commas (and other unpleasant characters I
don't want to think about) and spaces are probably asking for trouble.
The next example shows the general form for a node
specification, in which you want to specify all of a node's
links by hand:(1)
\section1[This-Node,Next-Node,Prev-Node,Up-Node]{Bar Semantics}
A `?' may be given for any of the four node-names; then the default is
used:
- 1. The default node-name is the section number.
- 2. The default
next-node is the one associated with the next same-level sectioning
command (i.e., the next `\section<n>' command if this is a
`\section<n>' command.
- 3. Analogously for the default
previous-node...
- 4. The default up-node is the last-seen
next-level-up sectioning command, e.g., if at a `\section<n>', then the
last `\section<n-1>' command seen.
Any text before the first
`\section' command goes in node `Top', which has node
specification "`Top,,,(dir)'".
The recommended form `\section[Foo-Sem]{Foo Semantics}' is
just short for `\section1[Foo-Sem,?,?,?]{Foo Semantics}'.
Additional Info nodes that are unrelated to sectioning commands may be
added with the `\node' command. [Note: not well tested.]
If you want a LaTeX-style sectioning command (e.g., to
specify a table-of-contents entry), use `onlyinfo' and `onlylatex'
environments.
---------- Footnotes ----------
(1)
Ignore the rest of this
section unless you enjoy pain -- it presumes
some familiarity with Texinfo/Info
specifics; see `info info' and/or `info texinfo'.