bug#70382: 29.3; Info-fontify-node renders cross-references misleadingly

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 14 Apr 2024 16:35:41 +0200
> From: Matt <matt@excalamus.com>
> 
> 6. Open 'texinfo.info' in Emacs:
> 
>     emacs -Q texinfo.info
> 
> 7. Go to line 3570 (M-g M-g 3570)
> 
> 8. Observe that the texinfo source matches the command-line info reader:
> 
>     ‘@xref’
>          Used to start a sentence with an Info cross-reference saying ‘*Note
>          NAME: NODE.’ or with 'See ...' in other output formats.
> 
>     ‘@ref’
>          Used within or, more often, at the end of a sentence; produces an
>          Info cross-reference saying ‘*note NAME: NODE.’, and just the
>          reference in other output formats, without the preceding 'See'.
> 
> 9. Open 'texinfo.info' using the Emacs info reader using 'C-u C-h i texinfo.info'
> 
> 10. Press 6 1 to navigate to "5.1 Different Cross-reference Commands"
> 
> 11. Observe that both "*Note" and "*note" are rendered as lowercase "see":
> 
>     ‘@xref’
>          Used to start a sentence with an Info cross-reference saying ‘see
>          NAME.’ or with 'See ...' in other output formats.
> 
>     ‘@ref’
>          Used within or, more often, at the end of a sentence; produces an
>          Info cross-reference saying ‘see NAME.’, and just the
>          reference in other output formats, without the preceding 'See'.
> 
> This is a problem because 'makeinfo' does *not* compile texinfo to other formats as described by the Emacs rendered version of the Texinfo info manual!  Specifically, 'makeinfo' renders @xref as (capital 'S') "See" in HTML and other formats.  The Emacs rendering misleads readers to believe that @xref renders as (lowercase 's') "see" in HTML and other formats.
> 
> I attempted a fix and was unsuccessful.  Emacs controls the default rendering of info files, in part, with 'Info-hide-note-references'.  The default for 'Info-hide-note-references' is to "replace '*note' with 'see'."  Unfortunately, 'Info-fontify-node', which handles the actual rendering, ignores case sensitivity.  This causes a match on "*Note", which corresponds to @xref commands, to be considered as "*note" and, because of the default behavior of 'Info-hide-note-references', to be replaced with (lowercase 's') "see ".
> 
> In the attached diff, I attempted to make the default 'Info-hide-note-references' behavior match the description in the texinfo.texi document for HTML.  That is, to replace "See" for @xref related notes (capital 'N' "*Note").  I attempted to differentiate which type of "note" pattern was matched.  However, I was unable to get the match to work correctly.  Despite setting 'case-fold-search' to nil, lowercase "*note" was still matched and incorrectly replaced the same as @xref.

Thanks.

The problem here is not the case-sensitivity.  The problem is that
info.el, the Emacs Info reader, attempts to decide whether to display
"See" or "see" based on the surrounding text (such as whether the
reference is at the beginning of a sentence etc.).  This does not work
in that specific node of the Texinfo manual, because it specifically
shows what makeinfo produces in the Info file, not how the references
will look in the reader.  You will see that the paragraph about @ref
in that section is also shown incorrectly (the Emacs Info reader
doesn't show "see" for @ref), and the paragraph about @pxref
incorrectly says the result starts with "*note" (it actually starts
with "see").

I think the only sane way of dealing with this problem is to disable
Info-hide-note-references in that particular node (and any other
nodes, if we find them, where there's a similar issue).  The patch
below attempts to do that.

Juri and Stefan, do you see a cleaner solution?

diff --git a/lisp/info.el b/lisp/info.el
index b459406..24b4402 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -4876,6 +4876,9 @@ Info-breadcrumbs
     ;; 				    'font-lock-face 'header-line line)
     line))
 
+(defvar info--dont-hide-references
+  '(("texinfo" "Cross Reference Commands"))
+  "Manuals and nodes where `Info-hide-note-references' should be ignored.")
 (defun Info-fontify-node ()
   "Fontify the node."
   (save-excursion
@@ -4893,6 +4896,14 @@ Info-fontify-node
                  (or (eq Info-fontify-maximum-menu-size t)
 		     (< (- (point-max) (point-min))
 			Info-fontify-maximum-menu-size))))
+           (Info-hide-note-references
+            (if (member Info-current-node
+                        (assoc-string
+                         (file-name-sans-extension
+                          (file-name-nondirectory Info-current-file))
+                         info--dont-hide-references t))
+                nil
+              Info-hide-note-references))
            rbeg rend)
 
       ;; Fontify header line