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: node-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 (see section @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.

This document was generated on October 2, 2013 using texi2html 5.0.