texinfo: Three Arguments

@xref

Four and Five Arguments

Two Arguments

Back to Software 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.

  The third argument to the xref commands must observe the same
restrictions as node names described in Note: Node Line Requirements.
The issue you're most likely to run into is that commas, periods, and
colons cannot be used.

  Also, 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, 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, for details.

in Info and

     See Section 5.2 [Thunder and Lightning], page 57, for details.

in a printed manual.

  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.

  If you want the section title to be used by default instead of node
names in cross references (an explicitly specified third argument still
takes precedence), Texinfo can do this automatically:

     @xrefautomaticsectiontitle on

  Typically this line would be given near the beginning of the document
and used for the whole thing.  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.