6.3 Parts of a Cross-reference

A cross-reference command requires only one argument, which is the name of the node to which it refers. Here is a simple example:

@xref{Node name}.

In Info output, this produces

*Note Node name::.

In a printed manual, the output is

See Section nnn [Node name], page ppp.

A cross-reference command may contain up to four additional arguments. By using these arguments, you can provide a cross-reference name, a topic description or section title for the printed output, the name of a different manual file, and the name of a different printed manual. To refer to another manual as a whole, the manual file and/or the name of the printed manual are the only required arguments (see Referring to a Manual as a Whole).

Here is an example of a full five-part cross-reference:

@xref{Node name, Online Label, Printed Label,
info-file-name, A Printed Manual}, for details.

which produces

*Note Online Label: (info-file-name)Node name,
for details.

in Info and

See section “Printed Label” in A Printed Manual, for details.

in a printed book.

The five possible arguments for a cross-reference are:

1. The node or anchor name (required, except for reference to whole manuals). This is the location to which the cross-reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document. Use @node to define the node (see Writing a Node), or @anchor (see @anchor).

   Write a node name in a cross-reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the formatters may not find the reference.

2. A label for online output. It is usually omitted; then the topic description (third argument) is used if it was specified; if that was omitted as well, the node name is used.
3. A label for printed output. Often, this is the title or topic of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used.
4. The name of the manual file in which the reference is located, if it is different from the current file. This name is used both for Info and HTML.
5. The name of a printed manual from a different Texinfo file.

The template for a full five argument cross-reference looks like this:

@xref{node-name, online-label, printed-label,
info-file-name, printed-manual-title}

Whitespace before and after the commas separating these arguments is ignored. To include a comma in one of the arguments, use @comma{} (see Inserting a Comma).

When processing with TeX, a comma is automatically inserted after the page number for cross-references to within the same manual, unless the closing brace of the argument is followed by non-whitespace (such as a comma or period). This gives you the choice of whether to have a comma there in Info or HTML output. For example,

@xref{Another Section} for more information

produces ‘See Another Section, page ppp, for more information’ in the printed output, and ‘*Note Another Section:: for more information’ in the Info output.

If an unwanted comma is added, follow the argument with a command such as ‘@:’. For example, ‘@xref{Hurricanes}@: --- for the details’ produces

See Hurricanes, page ppp — for the details

instead of ‘See Hurricanes, page ppp, — for the details’.

Cross-references with one, two, three, four, and five arguments are described separately following the description of @xref.

makeinfo warns when the text of a cross-reference (and node names and menu items) contains a problematic construct that will interfere with its parsing in Info. If you don’t want to see the warnings, you can set the customization variable INFO_SPECIAL_CHARS_WARNING to ‘0’ (see Other Customization Variables).