> From: Gavin Smith <[email protected]>
> Date: Fri, 1 Aug 2025 23:09:10 +0100
> Cc: [email protected]
>
> The last sentence here was an attempt to work around the limitations of
> Info format. @pxref{foo} and @ref{foo} have identical output in Info
> ("*note foo::"), but in other output formats, @pxref{foo} generates
> "see foo" and @ref generates "foo". Some attempt is made in the Info
> browsers to improve the display of Info files by displaying "*node foo::"
> as "see foo" or "foo". This is done with the Info-hide-note-references
> variable in Emacs or the hide-note-references variable in the standalone
> Info reader. However there is no way to know by looking at "*note foo::"
> in an Info file whether this originated as "@pxref{foo}" or "@ref{foo}".
>
> The text in the manual was to suggest that if the user wanted "see foo",
> they could write this as "see @ref{foo}", tranferring to Info as
> "see *note foo::". The Info brower could simply hide the "*note " text,
> rendering this as "see foo".
I agree with what the manual tries to convey. I would only like to
add that, historically, @pxref was only ever used in parentheses, so
this issue never surfaced. It is only due to changes in recent
Texinfo versions, which made @pxref and @ref closer in their output,
that the confusion as for which one to use could arise.
So my firm recommendation is to never use @ref as the last
cross-reference in parentheses, and never use @pxref outside of
parentheses. Using them contrary to that recommendation will "mostly
work", but will be sub-optimal in quite a few cases, as Gavin
explains.
> +The effect of @samp{@@pxref@{@var{node-name}@}} is identical to that of
> +@samp{@@ref@{@var{node-name}@}} in Info output. Hence, it may be
> +preferable, when not inside parentheses, to write
> +@samp{see @@ref@{@var{node-name}@}} rather
> +than @samp{@@pxref@{@var{node-name}@}} when you want the word ``see''
> +to occur in the output, as Info readers cannot reliably insert this
> +word based on the @samp{*note} cross-reference marker.
This looks like a good change, thanks.
