From: Matt <matt@excalamus.com>
To: 70382@debbugs.gnu.org
Subject: bug#70382: 29.3; Info-fontify-node renders cross-references misleadingly
Date: Sun, 14 Apr 2024 16:35:41 +0200 [thread overview]
Message-ID: <18edd090d56.b4d9f833651238.7754717828208203833@excalamus.com> (raw)
[-- 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
next reply other threads:[~2024-04-14 14:35 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-14 14:35 Matt [this message]
2024-04-14 16:21 ` bug#70382: 29.3; Info-fontify-node renders cross-references misleadingly Eli Zaretskii
2024-04-14 18:43 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-04-14 19:16 ` Eli Zaretskii
2024-04-15 6:55 ` Juri Linkov
2024-04-15 11:39 ` Eli Zaretskii
2024-04-15 12:49 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=18edd090d56.b4d9f833651238.7754717828208203833@excalamus.com \
--to=matt@excalamus.com \
--cc=70382@debbugs.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).