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