Hello,

On 25 February 2013 14:01, Subhan Tindall <subhan.tindall@rentrakmail.com> wrote:
The point being that compiling .texinfo source into an Info file
treats references differently. For example:
(@pxref{my_node_name}).  will compile just fine.
(@ref{my_node_name}). will not.  

Both work perfectly fine for me.
makeinfo (GNU texinfo) 5.0
 
There are also differences in case
(see v. See, note v. Note), and differences in output by ref type
depending on target output of file (info, DVI, HTML,...). For example,
@pxref generates different punctuation for typeset v. info files, @ref
does not generate a 'See ' in printed material while @xref does, etc.

Although the differences are subtle, they really are not equivalent
and should not be treated as such.
 
With a slight amount of work on the user's part, they can be made
functionally equivalent on export.

Using the two attached minimal .texi files (good-ref.texi is using
@xref/@pxref as is preferred while ref.texi is using @ref with
appropriate See/see added in the text) and disregarding filename
differences (since they are noted in the info output) I get the
following differences:

> makeinfo --html --no-split good-ref.texi ref.texi
0 Diffs

> makeinfo --docbook --no-split good-ref.texi ref.texi
Filename ID appears in diff

> makeinfo --xml --no-split good-ref.texi ref.texi
Filename difference.

Links are different since TexinfoML does still distinguish xref/pxref
and ref in how they create the links.

> makeinfo --no-split good-ref.texi ref.texi

The info file does show the expected differences between the two
documents, notably that the "@xref{}" becomes "*Note" while the
equivalent "See @ref{}" becomes "See *note" with @pxref{}->*note vs
see @ref{} -> see *note.

However once they are viewed within the *info* buffer (C-u C-h i
good-ref.info/ref-only.info) the lines in question are visually
identical since *Note becomes "See" and *note becomes "see" if there
is not already "see" present.

I will not disagree that @ref, @pxref and @xref are subtly different,
however with slight user intervention @ref can be used in the same
above locations by simply replacing:

@xref{}  -> "See @ref{}"
@pxref{} -> "see @ref{}"

I had to compare these possible outcomes when working on the texinfo
exporter.  Since links are parsed before being included in their
paragraphs, I did not have a way to obtain context and therefore
attempt to guess (and be successful) at which type of reference was
intended by a link in Org.  Restricting it to @ref{} in all cases,
even if it added a slight burden to the user (4 additional characters
to type in Org) if they wanted to emulate @xref or @pxref was in my
opinion the best choice.

Regards,

--
Jon

[...]