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 bug report
#70382: 29.3; Info-fontify-node renders cross-references misleadingly
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 70382 <at> debbugs.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)]
> 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.
[Message part 3 (message/rfc822, inline)]
[Message part 4 (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)]
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.