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

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

[Matt]

[-- Attachment #1: Type: text/plain, Size: 3847 bytes --]

Authors of GNU documentation who use Emacs to read the Texinfo info manual are misled by the default settings into using the wrong Texinfo commands.

The following uses:
- info (GNU texinfo) 7.1
- tar

1. Download the latest version of the texinfo info manual (version 7.1, 18 October 2023): https://www.gnu.org/software/texinfo/manual/texinfo/

2. Extract 'texinfo.info' from the tarball:

    tar xzvf texinfo.info.tar.gz

3. Open 'texinfo.info' in the Info reader:

    info ./texinfo.info

4. Press 6 1 to navigate to "5.1 Different Cross-reference Commands"

5. Observe that @xref uses (capital 'N') "*Note" and @ref uses (lowercase 'n') "*note":

    ‘@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'.

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.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

[-- Attachment #2: v01-make-Info-hide-note-references-render-more-like-command-line-info-reader.diff --]
[-- Type: application/octet-stream, Size: 664 bytes --]

diff --git a/lisp/info.el b/lisp/info.el
index b459406959e..1b0fee0efac 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -5038,6 +5038,14 @@ first line or header line, and for breadcrumb links.")
 				 (save-excursion
 				   (search-forward "\n\n" start t)))
 			       "See ")
+			      ((save-match-data (let ((case-fold-search nil))
+				 (save-excursion
+				   (search-forward "*Note" next t)))
+			       "Banana "))
+			      ((save-match-data (let ((case-fold-search nil))
+				 (save-excursion
+				   (search-forward "*note" next t)))
+			       "banana "))
 			      (t "see "))))
                 (goto-char next)
                 (add-text-properties

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

[Eli Zaretskii]

> 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

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> 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").

Yes, our prettifying of cross-references gets confused here because it
mistakes the doc's text for a cross-reference (because that text is
indeed showing an example of what such cross-references look like).

Given that the Info format doesn't document what the actual text should
look like, our prettifying can only be heuristic.

Notice that even if you set `Info-hide-note-references` to nil,
the "*Note NAME: NODE." is still highlighted if it were an actual
cross-reference (and if you click on it you jump to the "node" node).
In the Info reader, the behavior is almost the same: this example is
also highlighted but if you hit RET on it it signals an error because it
can't find a node named "NODE" (looks like `/usr/bin/info` is case
sensitive while Emacs's Info reader is not).

IOW, Texinfo's own reader gets confused by its own doc.

> 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.

Sounds OK.

> Juri and Stefan, do you see a cleaner solution?

We could try and detect that the cross ref is within a '...'.

BTW, I'm not sure whether the current behavior is really a problem:
after all, in Emacs, people indeed won't see something of the form
`*note NAME: NODE.` but they'll see something of the form `see NAME` or
`See NAME`, so the bug could be considered a feature (depending on
whether we think the doc describes the content of the Info file or
whether it describes when readers will see when reading their doc in
Emacs).


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: matt@excalamus.com,  Juri Linkov <juri@linkov.net>,  70382@debbugs.gnu.org
> Date: Sun, 14 Apr 2024 14:43:31 -0400
> 
> > 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.
> 
> Sounds OK.

OK, I will install this soon, unless Juri (or someone else) comes up
with something more elegant.

> > Juri and Stefan, do you see a cleaner solution?
> 
> We could try and detect that the cross ref is within a '...'.

That would fail in other cases.

> BTW, I'm not sure whether the current behavior is really a problem:
> after all, in Emacs, people indeed won't see something of the form
> `*note NAME: NODE.` but they'll see something of the form `see NAME` or
> `See NAME`, so the bug could be considered a feature (depending on
> whether we think the doc describes the content of the Info file or
> whether it describes when readers will see when reading their doc in
> Emacs).

Yes, but here we make worse mistakes: not only we should "see" with
wrong capitalization, we also make the impression that @ref shows as
"see" in Emacs (it doesn't) and @pxref shows "*note" (it shows "see").

(I think the text should have a note that in Emacs these
cross-references will look differently, but that's a patch to be
submitted to the Texinfo developers.)

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

[Juri Linkov]

>> > 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.
>>
>> Sounds OK.
>
> OK, I will install this soon, unless Juri (or someone else) comes up
> with something more elegant.

Like many self-reference cases this needs an exception too, so probably
there is no better way than info--dont-hide-references (maybe this name
should be upper-cased to Info--dont-hide-references like other Info variables).

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

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  matt@excalamus.com,
>   70382@debbugs.gnu.org
> Date: Mon, 15 Apr 2024 09:55:19 +0300
> 
> >> > 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.
> >>
> >> Sounds OK.
> >
> > OK, I will install this soon, unless Juri (or someone else) comes up
> > with something more elegant.
> 
> Like many self-reference cases this needs an exception too, so probably
> there is no better way than info--dont-hide-references (maybe this name
> should be upper-cased to Info--dont-hide-references like other Info variables).

I named it "info--*" so that this internal variable doesn't get in the
way when one completes on Info variable names.  But I see now that we
already have quite a few internal names that start with "Info--", so I
guess that ship has sailed long ago.

Thanks for the feedback, will install soon.

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

[Eli Zaretskii]

> Cc: 70382@debbugs.gnu.org, monnier@iro.umontreal.ca, matt@excalamus.com
> Date: Mon, 15 Apr 2024 14:39:02 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Juri Linkov <juri@linkov.net>
> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  matt@excalamus.com,
> >   70382@debbugs.gnu.org
> > Date: Mon, 15 Apr 2024 09:55:19 +0300
> > 
> > >> > 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.
> > >>
> > >> Sounds OK.
> > >
> > > OK, I will install this soon, unless Juri (or someone else) comes up
> > > with something more elegant.
> > 
> > Like many self-reference cases this needs an exception too, so probably
> > there is no better way than info--dont-hide-references (maybe this name
> > should be upper-cased to Info--dont-hide-references like other Info variables).
> 
> I named it "info--*" so that this internal variable doesn't get in the
> way when one completes on Info variable names.  But I see now that we
> already have quite a few internal names that start with "Info--", so I
> guess that ship has sailed long ago.
> 
> Thanks for the feedback, will install soon.

Now done on master, and closing the bug.