texinfo: Four and Five Arguments

@xref

Three Arguments

Back to Software Index

8.4.5 '@xref' with Four and Five Arguments
------------------------------------------

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

  Remember that a comma or period must follow the closing brace of an
'@xref' command to terminate the cross reference.

The full template is:

     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
     INFO-FILE-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.

As you can see, the name of the Info file is enclosed in parentheses and
precedes the name of the node.

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 TeX cannot know to which page a
reference refers when that reference is to another manual.

  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 Info.
For example,

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

produces

     Note: Thunder and Lightning.

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.

  A very unusual case: you may want to refer to another manual file that
is within a single printed manual--when multiple Texinfo files are
incorporated into the same TeX run but can create separate Info or HTML
output files.  In this case, you need to specify only the fourth
argument, and not the fifth.

  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.