texinfo: @pxref

Cross References

@inforef

@ref

Back to Software Index

8.7 '@pxref'
============

The parenthetical reference command, '@pxref', is nearly the same as
'@xref', but it is best used at the end of a sentence or before a
closing parenthesis.  The command differs from '@xref' in two ways:

  1. TeX typesets the reference for the printed manual with a lowercase
     'see' rather than an uppercase 'See'.

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

  '@pxref' is designed so that the output looks right and works right at
the end of a sentence or parenthetical phrase, 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) ...

in Info and

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

in a printed manual.

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

     ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...

which produces

     ... (Note: CROSS-REFERENCE-NAME.) ...

in Info and

     ... (see Section NNN [NODE-NAME], page PPP) ...

in a printed manual.

  '@pxref' can be used with up to five arguments, just like '@xref'
(Note: @xref).

  In past versions of Texinfo, it was not allowed to write punctuation
after an '@pxref', so it could be used _only_ before a right
parenthesis.  This is no longer the case, so now it can be used (for
example) at the end of a sentence, where a lowercase "see" works best.
For instance:

     ... For more information, @pxref{More}.

which outputs (in Info):

     ... For more information, Note: More.

In general, '@pxref' should only be followed by a comma, period, or
right parenthesis; in other cases, 'makeinfo' has to insert a period to
make the cross reference work correctly in Info, and that period looks
wrong.

  As a matter of style, '@pxref' is best used at the ends of sentences.
Although it technically works in the middle of a sentence, that location
breaks up the flow of reading.