5.2 Parts of a Cross-reference

A cross-reference command requires only one argument, which is the name of the node to which it refers. A cross-reference command may contain up to four additional arguments. The template for a full five argument cross-reference looks like this:

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

The five possible arguments for a cross-reference are:

  1. The node or anchor name. 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 Line), @anchor (see @anchor: Defining Arbitrary Cross-reference Targets), or @float (see @float [type][,label]: Floating Material) with a label. This argument is required (except for reference to whole manuals).

    Write a node name in a cross-reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the processors 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 to which the reference refers, if it is outside the current manual, in a different Texinfo file.
  5. The title of the printed manual to which the reference refers, from a different Texinfo file.

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

Cross-references with one, two, three, four, and five arguments are described separately in following sections.

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 other output formats. For example,

@xref{Another Section} for more info

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

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’.

texi2any warns and protect names when the text of a cross-reference (and node names and menu items) contains a problematic construct that could interfere with its parsing in Info. See Info Node Names Constraints.