GNU bug report logs -
#70382
29.3; Info-fontify-node renders cross-references misleadingly
Previous Next
Reported by: matt <at> excalamus.com
Date: Sun, 14 Apr 2024 14:37:03 UTC
Severity: normal
Found in version 29.3
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your message dated Mon, 15 Apr 2024 15:49:16 +0300
with message-id <86il0ilrjn.fsf <at> gnu.org>
and subject line Re: bug#70382: 29.3; Info-fontify-node renders cross-references misleadingly
has caused the debbugs.gnu.org bug report #70382,
regarding 29.3; Info-fontify-node renders cross-references misleadingly
to be marked as done.
(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)
--
70382: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=70382
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
[Message part 3 (text/plain, inline)]
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
[v01-make-Info-hide-note-references-render-more-like-command-line-info-reader.diff (application/octet-stream, attachment)]
[Message part 5 (message/rfc822, inline)]
> Cc: 70382 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca, matt <at> excalamus.com
> Date: Mon, 15 Apr 2024 14:39:02 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
>
> > From: Juri Linkov <juri <at> linkov.net>
> > Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, matt <at> excalamus.com,
> > 70382 <at> 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.
This bug report was last modified 1 year and 94 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.