On Fri, Aug 01, 2025 at 03:30:29AM +0000, Werner LEMBERG wrote:
>
> In the section documenting `@pxref` there is the following paragraph.
>
> In past versions of Texinfo, it was not allowed to write
> punctuation after a ‘@pxref’, so it could be used _only_ before a
> right parenthesis. This is no longer the case. The effect of
> ‘@pxref{NODE-NAME}’ is similar to that of ‘see @ref{NODE-NAME}’.
> However, in many circumstances the latter is preferable, as this
> makes it clear in the Info output that the word "see" should be
> present.
>
> I don't understand what the last sentence means; please elaborate. As
> far as I understand the issue, `see @ref{}` should be avoided for the
> sake of Info output. In other words, it is better to write
>
> ```
> Foo equals bar; @pxref{This} and @ref{That}.
> Foo equals bar; @pxref{This}.
> ```
>
> to get
>
> ```
> Foo equals bar; *note This:: and *note That::.
> Foo equals bar; *note This::.
> ```
>
> What am I missing?
>
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".
So to get "see foo and bar", you would use the Info markup:
"see *note foo:: and *note bar::". In Texinfo this would be:
"see @ref{foo} and @ref{bar}."
There is this comment in the Info browser source code (in info/scan.c):
/* Only output the "see" for input like "(*note ...)", which
would have come from a use of @pxref. We used to output "see" for
"*note" in more circumstances, with a list of words where to
suppress it (to avoid "see *note" turning into "see see"), but
such a list can't be complete or reliable. It's better to remove
it with more enthusiasm, then if the document writer wants a "see"
to appear, they can add one themselves. */
(The old version of the code referred to was in a function called
'avoid_see_see'.)
However, there is probably not exactly consistent behaviour across the
two Info readers in this regard.
This is not a perfect solution, however, as hiding the "*note" text yields
a shorter line, and it is not possible to refill the paragraphs reliably
in Info format. For example, from the groff manual:
This section only documents options to the 'groff' front end. Many
of the arguments to 'groff' are passed on to 'gtroff', therefore those
are also included. Arguments to pre- or postprocessors can be found in
*note Invoking gpic::, *note Invoking geqn::, *note Invoking gtbl::,
*note Invoking ggrn::, *note Invoking grefer::, *note Invoking gchem::,
*note Invoking gsoelim::, *note Invoking preconv::, *note Invoking
grotty::, *note Invoking grops::, *note Invoking gropdf::, *note
Invoking grohtml::, *note Invoking grodvi::, *note Invoking grolj4::,
*note Invoking grolbp::, and *note Invoking gxditview::.
This becomes:
This section only documents options to the 'groff' front end. Many
of the arguments to 'groff' are passed on to 'gtroff', therefore those
are also included. Arguments to pre- or postprocessors can be found in
Invoking gpic, Invoking geqn, Invoking gtbl,
Invoking ggrn, Invoking grefer, Invoking gchem,
Invoking gsoelim, Invoking preconv, Invoking
grotty, Invoking grops, Invoking gropdf,
Invoking grohtml, Invoking grodvi, Invoking grolj4,
Invoking grolbp, and Invoking gxditview.
Personally, although I implemented the "hide-note-references" variable
in the stand-alone browser in the hope it would lead to making Info
easier to use (as I had found the "*note" syntax confusing and annoying
when using Info), now I don't use it, as I find stylistic changes such
as underlining sufficient for marking such cross-references in Info
(formerly, there was no such styling).
The wording in the manual could be improved as the word "see" is not
inherent to the Info output for these constructs. I've made an attempt
in the following commit.
commit 85454431b4e724baadc6d99ede03a98f4f43e6fa
Author: Gavin Smith <[email protected]>
Date: 2025-08-01 23:01:17 +0100
* doc/texinfo.texi (@pxref):
Attempt at clarifying why "see @ref" may often be better
than "@pxref".
diff --git a/ChangeLog b/ChangeLog
index ab3e98791f..a812c73a2b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2025-08-01 Gavin Smith <[email protected]>
+
+ * doc/texinfo.texi (@pxref):
+ Attempt at clarifying why "see @ref" may often be better
+ than "@pxref".
+
2025-08-01 Gavin Smith <[email protected]>
* util/htmlxref.d/Texinfo_GNU.cnf (mit-scheme-*):
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 2faa44ce3d..d1083ea160 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -4373,13 +4373,17 @@ @node @code{@@pxref}
@noindent
in a printed manual.
+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.
+
In past versions of Texinfo, it was not allowed to write punctuation
after a @code{@@pxref}, so it could be used @emph{only} before a
right parenthesis. This is no longer the case.
-The effect of @samp{@@pxref@{@var{node-name}@}} is similar to that of
-@samp{see @@ref@{@var{node-name}@}}. However, in many circumstances the
-latter is preferable, as this makes it clear in the Info output that
-the word ``see'' should be present.
@node @code{@@anchor}
