5.6 @xref with Four and Five Arguments

In a cross-reference, a fourth argument specifies the name of another manual, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual.

The full template is:

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

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}.

produces this output in Info:

*Note Lightning: (weather)Electrical Effects.

As you can see, the name of the manual is enclosed in parentheses and precedes the name of the node. In HTML, the manual name and the node name are used to construct the hyperlink URL (see HTML Cross-references), while the link text is based on the label.

In a printed manual, the reference looks like this:

See section “Thunder and Lightning” in An Introduction to Meteorology.

The title of the printed manual is typeset like @cite; and the reference lacks a page number since the page a reference refers when that reference is to another manual cannot be known.

Next case: often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will be used as the cross-reference name in online formats. For example,

@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}.

produces

*Note Thunder and Lightning: (weather)Electrical Effects.

in Info and

See section “Thunder and Lightning” in An Introduction to Meteorology.

in a printed manual.

Next case: If the node name and the section title are the same in the other manual, you may also leave out the section title. In this case, the node name is used in both instances. For example,

@xref{Electrical Effects,,,
weather, An Introduction to Meteorology}.

produces

*Note (weather)Electrical Effects::.

in Info and

See section “Electrical Effects” in An Introduction to Meteorology.

in a printed manual.

In general, there is no reason to have a manual name argument without a printed manual argument, unless no printed manual is generated. You may also want to refer to another manual file that is within a single printed manual—when multiple Texinfo files are incorporated into the same printed manual but can create separate output files in other output formats. In this case, you need to specify only the fourth argument, and not the fifth. If the printed manual title argument is missing, the manual name will be used instead in printed output.

A printed manual title argument without an online manual argument is of little use unless only a printed manual is generated from the Texinfo source. The result in online formats depends on the format, and can be, for example, an empty manual name or a reference to the printed manual formatted in a similar way to the printed output.

Finally, it’s also allowed to leave out all the arguments except the fourth and fifth, to refer to another manual as a whole. See the next section.