texinfo: @ref

Cross References

@pxref

Top Node Naming

Back to Software Index

8.6 '@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, @pxref{This}, and @ref{That}.

produces in Info:

     For more information, Note: This, and Note: That.

and in printed output:

     For more information, see Section 1.1 [This], page 1, and Section
     1.2 [That], page 2.

  The '@ref' command can tempt 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 could be using both the printed
and the Info format.  For example:

     Sea surges are described in @ref{Hurricanes}.

looks ok in the printed output:

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

but is awkward to read in Info, "note" being a verb:

     Sea surges are described in Note: Hurricanes.

  You should write a period or comma immediately after an '@ref' command
with two or more arguments.  If there is no such following punctuation,
'makeinfo' will generate a (grammatically incorrect) period in the Info
output; otherwise, the cross reference would fail completely, due to the
current syntax of Info format.

  In general, it is best to use '@ref' only when you need some word
other than "see" to precede the reference.  When "see" (or "See") is ok,
'@xref' and '@pxref' are preferable.