[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
8.4.4 @xref
with Three Arguments
A third argument replaces the node name in the TeX output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section. Often, you will want to use initial uppercase letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning.
Remember to write a comma or period after the closing brace of an
@xref
to terminate the cross reference. In the following
examples, a clause follows a terminating comma.
The template is like this:
@xref{node-name, cross-reference-name, title-or-topic}.
For example,
@xref{Electrical Effects, Lightning, Thunder and Lightning}, for details.
produces
*Note Lightning: Electrical Effects, for details.
in Info and
See Section 5.2 [Thunder and Lightning], page 57, for details.
in a printed manual.
If a third argument is given and the second one is empty, then the third argument serves for both. (Note how two commas, side by side, mark the empty second argument.)
@xref{Electrical Effects, , Thunder and Lightning}, for details.
produces
*Note Thunder and Lightning: Electrical Effects, for details.
in Info and
See Section 5.2 [Thunder and Lightning], page 57, for details.
in a printed manual.
The third argument to cross references must observe some of the
restrictions for node names (see section @node
Line Requirements). The
most common issue is that colons cannot be used, since that interferes
with the parsing of the Info file.
As a practical matter, it is often best to write cross references with just the first argument if the node name and the section title are the same (or nearly so), and with the first and third arguments only if the node name and title are different.
Texinfo offers a setting to use the section title instead of node names by default in cross references (an explicitly specified third argument still takes precedence):
@xrefautomaticsectiontitle on
Typically this line would be given near the beginning of the document
and used for the whole manual. But you can turn it off if you want
(@xrefautomaticsectiontitle off
), for example, if you’re
including some other sub-document that doesn’t have suitable section
names.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on October 2, 2013 using texi2html 5.0.