On Sat, Aug 02, 2025 at 09:28:14AM +0300, Eli Zaretskii wrote:
> > 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.
What do you think of multiple cross-references in parentheses: you
advise against "(see @ref{foo} and @ref{bar})" and apparently would
favour "(see @ref{foo} and @pxref{bar})" or "(@pxref{foo} and @pxref{bar})".
Why is that?
