8 Cross References
******************

Cross references are used to refer the reader to other parts of the
same or different Texinfo files.  In Texinfo, nodes and anchors are the
places to which cross references can refer.

* References::                  What cross references are for.
* Cross Reference Commands::    A summary of the different commands.
* Cross Reference Parts::       A cross reference has several parts.
* xref::                        Begin a reference with `See' ...
* Top Node Naming::             How to refer to the beginning of another file.
* ref::                         A reference for the last part of a sentence.
* pxref::                       How to write a parenthetical cross reference.
* inforef::                     How to refer to an Info-only file.
* uref::                        How to refer to a uniform resource locator.

References
----------
What References Are For
=======================

Often, but not always, a printed document should be designed so that
it can be read sequentially.  People tire of flipping back and forth
to find information that should be presented to them as they need
it.

However, in any document, some information will be too detailed for
the current context, or incidental to it; use cross references to
provide access to such information.  Also, an online help system or a
reference manual is not like a novel; few read such documents in
sequence from beginning to end.  Instead, people look up what they
need.  For this reason, such creations should contain many cross
references to help readers find other information that they may not
have read.

In a printed manual, a cross reference results in a page reference,
unless it is to another manual altogether, in which case the cross
reference names that manual.

In Info, a cross reference results in an entry that you can follow using
the Info `f' command.  (See (info)Some advanced Info commands.)

The various cross reference commands use nodes (or anchors,
see @anchor) to define cross reference locations.
This is evident in Info, in which a cross reference takes you to the
specified location.  TeX also uses nodes to define cross reference
locations, but the action is less obvious.  When TeX generates a DVI
file, it records each node's page number and uses the page numbers in making
references.  Thus, if you are writing a manual that will only be
printed, and will not be used online, you must nonetheless write
@node lines to name the places to which you make cross
references.

8.1 Different Cross Reference Commands
======================================

There are four different cross reference commands:

@xref
Used to start a sentence in the printed manual saying `See ...'
or an Info cross-reference saying `*Note name: node.'.

@ref
Used within or, more often, at the end of a sentence; same as
@xref for Info; produces just the reference in the printed
manual without a preceding `See'.

@pxref
Used within parentheses to make a reference that suits both an Info
file and a printed book.  Starts with a lower case `see' within the
printed manual. (`p' is for `parenthesis'.)

@inforef
Used to make a reference to an Info file for which there is no printed
manual.

(The @cite command is used to make references to books and
manuals for which there is no corresponding Info file and, therefore,
no node to which to point.   See @cite.)

8.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.  But a cross reference command
may contain up to four additional arguments.  By using these
arguments, you can provide a cross reference name for Info, a topic
description or section title for the printed output, the name of a
different Info file, and the name of a different printed
manual.

Here is a simple cross reference example:

@xref{Node name}.

which produces

*Note Node name::.

and

See Section nnn [Node name], page ppp.

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

@xref{Node name, Cross Reference Name, Particular Topic,
info-file-name, A Printed Manual}, for details.

which produces

*Note Cross Reference Name: (info-file-name)Node name,
for details.

in Info and

See section "Particular Topic" 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).  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.

2. The cross reference name for the Info reference, if it is to be different
from the node name.  If you include this argument, it becomes
the first part of the cross reference.  It is usually omitted.

3. A topic description or section name.  Often, this is the title 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 Info file in which the reference is located, if it is
different from the current file.  You need not include any `.info'
suffix on the file name, since Info readers try appending it
automatically.

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, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

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

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.

You can write cross reference commands within a paragraph, but note
how Info and TeX format the output of each of the various commands:
write @xref at the beginning of a sentence; write
@pxref only within parentheses, and so on.

8.3 @xref
=========

The @xref command generates a cross reference for the
beginning of a sentence.  The Info formatting commands convert it into
an Info cross reference, which the Info `f' command can use to
bring you directly to another node.  The TeX typesetting commands
convert it into a page reference, or a reference to another book or
manual.

* Reference Syntax::            What a reference looks like and requires.
* One Argument::                @xref with one argument.
* Two Arguments::               @xref with two arguments.
* Three Arguments::             @xref with three arguments.
* Four and Five Arguments::     @xref with four and five arguments.

Reference Syntax
----------------
What a Reference Looks Like and Requires
----------------------------------------

Most often, an Info cross reference looks like this:

*Note node-name::.

or like this

*Note cross-reference-name: node-name.

In TeX, a cross reference looks like this:

See Section section-number [node-name], page page.

or like this

See Section section-number [title-or-topic], page page.

The @xref command does not generate a period or comma to end
the cross reference in either the Info file or the printed output.
You must write that period or comma yourself; otherwise, Info will not
recognize the end of the reference.  (The @pxref command works
differently.  See @pxref.)

Please note: A period or comma must follow the closing
brace of an @xref.  It is required to terminate the cross
reference.  This period or comma will appear in the output, both in
the Info file and in the printed manual.

@xref must refer to an Info node by name.  Use @node
to define the node (see Writing a Node).

@xref is followed by several arguments inside braces, separated by
commas.  Whitespace before and after these commas is ignored.

A cross reference requires only the name of a node; but it may contain
up to four additional arguments.  Each of these variations produces a
cross reference that looks somewhat different.

Please note: Commas separate arguments in a cross reference;
avoid including them in the title or other part lest the formatters
mistake them for separators.

8.3.1 @xref with One Argument
-----------------------------

The simplest form of @xref takes one argument, the name of
another node in the same Info file.    The Info formatters produce
output that the Info readers can use to jump to the reference; TeX
produces output that specifies the page and section number for you.

For example,

@xref{Tropical Storms}.

produces

*Note Tropical Storms::.

and

See Section 3.1 [Tropical Storms], page 24.

(Note that in the preceding example the closing brace is followed by a
period.)

You can write a clause after the cross reference, like this:

@xref{Tropical Storms}, for more info.

which produces

*Note Tropical Storms::, for more info.

and

See Section 3.1 [Tropical Storms], page 24, for more info.

(Note that in the preceding example the closing brace is followed by a
comma, and then by the clause, which is followed by a period.)

8.3.2 @xref with Two Arguments
------------------------------

With two arguments, the second is used as the name of the Info cross
reference, while the first is still the name of the node to which the
cross reference points.

The template is like this:

@xref{node-name, cross-reference-name}.

For example,

@xref{Electrical Effects, Lightning}.

produces:

*Note Lightning: Electrical Effects.

and

See Section 5.2 [Electrical Effects], page 57.

(Note that in the preceding example the closing brace is followed by a
period; and that the node name is printed, not the cross reference name.)

You can write a clause after the cross reference, like this:

@xref{Electrical Effects, Lightning}, for more info.

which produces
*Note Lightning: Electrical Effects, for more info.

and

See Section 5.2 [Electrical Effects], page 57, for more info.

(Note that in the preceding example the closing brace is followed by a
comma, and then by the clause, which is followed by a period.)

8.3.3 @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 upper case 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.

Remember to avoid placing a comma within the title or topic section of
a cross reference, or within any other section.  The formatters divide
cross references into arguments according to the commas; a comma
within a title or other section will divide it into two arguments.  In
a reference, you need to write a title such as "Clouds, Mist, and
Fog" without the commas.

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: Electrical Effects, for details.

and

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

If a third argument is given and the second one is empty, then the
third argument serves 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: Electrical Effects, for details.

and

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

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, and with the first and third arguments if the node name and title
are different.

Here are several examples from The GNU Awk User's Guide:

@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
   for more information.
@xref{Regexp, , Regular Expressions as Patterns}.

8.3.4 @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.  In the
following examples, a clause follows a terminating comma.

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

produces

*Note Lightning: (weather)Electrical Effects, for details.

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

The title of the printed manual is typeset in italics; and the
reference lacks a page number since TeX cannot know to which page a
reference refers when that reference is to another manual.

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.

The template looks like this:

@xref{node-name, , title-or-topic, info-file-name,
printed-manual-title}, for details.

which produces

*Note title-or-topic: (info-file-name)node-name, for details.

and

See section title-or-topic in printed-manual-title, for details.

For example,

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

produces

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

and

See section "Thunder and Lightning" in An Introduction to
Meteorology, for details.

On rare occasions, you may want to refer to another Info file that
is within a single printed manual--when multiple Texinfo files are
incorporated into the same TeX run but make separate Info files.
In this case, you need to specify only the fourth argument, and not
the fifth.

8.4 Naming a `Top' Node
=======================

In a cross reference, you must always name a node.  This means that in
order to refer to a whole manual, you must identify the `Top' node by
writing it as the first argument to the @xref command.  (This
is different from the way you write a menu entry; see Referring to Other Info Files.)  At the same time, to
provide a meaningful section topic or title in the printed cross
reference (instead of the word `Top'), you must write an appropriate
entry for the third argument to the @xref command.


Thus, to make a cross reference to The GNU Make Manual,
write:

@xref{Top, , Overview, make, The GNU Make Manual}.

which produces

*Note Overview: (make)Top.

and

See section "Overview" in The GNU Make Manual.

In this example, `Top' is the name of the first node, and
`Overview' is the name of the first section of the manual.
8.5 @ref
========

@ref is nearly the same as @xref except that it does
not generate a `See' in the printed output, just the reference itself.
This makes it useful as the last part of a sentence.

For example,

For more information, see @ref{Hurricanes}.

produces

For more information, see *Note Hurricanes::.

and

For more information, see Section 8.2 [Hurricanes], page 123.

The @ref command sometimes leads writers to express themselves
in a manner that is suitable for a printed manual but looks awkward
in the Info format.  Bear in mind that your audience will be using
both the printed and the Info format.

For example,

Sea surges are described in @ref{Hurricanes}.

produces

Sea surges are described in Section 6.7 [Hurricanes], page 72.

in a printed document, and the following in Info:

Sea surges are described in *Note Hurricanes::.

Caution: You must write a period, comma, or right
parenthesis immediately after an @ref command with two or more
arguments.  Otherwise, Info will not find the end of the cross reference
entry and its attempt to follow the cross reference will fail.  As a
general rule, you should write a period or comma after every
@ref command.  This looks best in both the printed and the Info
output.

8.6 @pxref
==========

The parenthetical reference command, @pxref, is nearly the
same as @xref, but you use it only inside parentheses
and you do not type a comma or period after the command's
closing brace.  The command differs from @xref in two
ways:

1. TeX typesets the reference for the printed manual with a lower case
`see' rather than an upper case `See'.

2. The Info formatting commands automatically end the reference with a
closing colon or period.

Because one type of formatting automatically inserts closing
punctuation and the other does not, you should use @pxref
only inside parentheses as part of another sentence.  Also, you
yourself should not insert punctuation after the reference, as you do
with @xref.

@pxref is designed so that the output looks right and works
right between parentheses both in printed output and in an Info file.
In a printed manual, a closing comma or period should not follow a
cross reference within parentheses; such punctuation is wrong.  But in
an Info file, suitable closing punctuation must follow the cross
reference so Info can recognize its end.  @pxref spares you
the need to use complicated methods to put a terminator into one form
of the output and not the other.

With one argument, a parenthetical cross reference looks like
this:

... storms cause flooding (@pxref{Hurricanes}) ...

which produces

... storms cause flooding (*Note Hurricanes::) ...

and

... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

With two arguments, a parenthetical cross reference has this
template:

... (@pxref{node-name, cross-reference-name}) ...

which produces

... (*Note cross-reference-name: node-name.) ...

and

... (see Section nnn [node-name], page ppp) ...

@pxref can be used with up to five arguments just like
@xref (see @xref).

Please note: Use @pxref only as a parenthetical
reference.  Do not try to use @pxref as a clause in a sentence.
It will look bad in either the Info file, the printed output, or
both.

Also, parenthetical cross references look best at the ends of sentences.
Although you may write them in the middle of a sentence, that location
breaks up the flow of text.

8.7 @inforef
============

@inforef is used for cross references to Info files for which
there are no printed manuals.  Even in a printed manual,
@inforef generates a reference directing the user to look in
an Info file.

The command takes either two or three arguments, in the following
order:

1. The node name.

2. The cross reference name (optional).

3. The Info file name.

Separate the arguments with commas, as with @xref.  Also, you
must terminate the reference with a comma or period after the
`}', as you do with @xref.

The template is:

@inforef{node-name, cross-reference-name, info-file-name},

Thus,

@inforef{Expert, Advanced Info commands, info},
for more information.

produces

*Note Advanced Info commands: (info)Expert,
for more information.

and

See Info file `info', node `Expert', for more information.

Similarly,

@inforef{Expert, , info}, for more information.

produces

*Note (info)Expert::, for more information.

and

See Info file `info', node `Expert', for more information.

The converse of @inforef is @cite, which is used to
refer to printed works for which no Info form exists.  See @cite.


8.8 @uref{url[, text][, replacement]}
=====================================

@uref produces a reference to a uniform resource locator (url).
It takes one mandatory argument, the url, and two optional arguments
which control the text that is displayed.  In HTML output, @uref
produces a link you can follow.

The second argument, if specified, is the text to display (the default
is the url itself); in Info and DVI output, but not in HTML output, the
url is also output.

The third argument, on the other hand, if specified is also the text to
display, but the url is not output in any format.  This is useful
when the text is already sufficiently referential, as in a man page.  If
the third argument is given, the second argument is ignored.

The simple one argument form, where the url is both the target and the
text of the link:

The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.

produces:
The official GNU ftp site is <ftp://ftp.gnu.org/gnu>.


An example of the two-argument form:
The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
holds programs and texts.

produces:
The official GNU ftp site <ftp://ftp.gnu.org/gnu>
holds programs and texts.

that is, the Info output is this:
The official GNU ftp site (ftp://ftp.gnu.org/gnu)
holds programs and texts.

and the HTML output is this:
The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
holds programs and texts.


An example of the three-argument form:
The @uref{/man.cgi/1/ls,,ls(1)} program ...

produces:
The ls(1) </man.cgi/1/ls> program ...

but with HTML:
The <a href="/man.cgi/1/ls">ls(1)</a> program ...

To merely indicate a url without creating a link people can follow, use
@url (see @url).

Some people prefer to display url's in the unambiguous format:

<URL:http://host/path>

You can use this form in the input file if you wish.  We feel it's not
necessary to clutter up the output with the extra `<URL:' and
`>', since any software that tries to detect url's in text already
has to detect them without the `<URL:' to be useful.


