bug#74844: 29.4; m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

bug#74844: 29.4; m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

[Suhail Singh]

The Texinfo entry in the "dir" and "m-buffer-doc.info" files are
malformed.  As a consequence the font-locking as well as the completion
for the Info-menu command are broken in the Top directory.  CC-ing
Stefan given his familiarity with documentation generation for the ELPA
package in question (based on git commits).

The @direntry for Texinfo is of the form ‘* DIRNAME: NODE.’ where ‘NODE’
is usually just ‘(FILENAME)’.  In the case of m-buffer it ought to be
something like "* m-buffer: (m-buffer-doc)."  However, the @direntry as
noted in the "dir" and "m-buffer-doc.info" files is "* m-buffer.doc."
As a result, `Info-follow-nearest-node' (bound to RET in Info-mode-map)
is unable to determine the appropriate node when point is on the
m-buffer-doc entry.  Digging deeper, the failure is due to the following
code resulting in nil:

#+begin_src emacs-lisp
  (Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
#+end_src

Fixing the direntry in the "dir" and "m-buffer-doc-info" files resolves
the issue.

Given that the documentation is generated from m-buffer-doc.org via
ox-texinfo, presumably the issue lies in the incorrect usage of the
obsolete TEXINFO_DIR_TITLE keyword.  Presumably the fix would be to use
the TEXINFO_FILENAME and, possibly, the TEXINFO_DIR_NAME keywords.
However, for some reason I am unable to generate the documentation
locally.  As such I am not submitting a patch.  Hope this helps.

In GNU Emacs 29.4 (build 2, x86_64-suse-linux-gnu, GTK+ Version 3.24.43,
cairo version 1.18.2)
System Description: openSUSE Tumbleweed

Configured using:
 'configure --disable-build-details --without-pop --with-mailutils
 --with-native-compilation --without-hesiod --with-gameuser=:games
 --with-kerberos --with-kerberos5 --with-file-notification=inotify
 --with-modules --enable-autodepend --prefix=/usr
 --mandir=/usr/share/man --infodir=/usr/share/info --datadir=/usr/share
 --localstatedir=/var --sharedstatedir=/var/lib
 --libexecdir=/usr/libexec --with-file-notification=yes
 --libdir=/usr/lib64
 --enable-locallisppath=/usr/share/emacs/29.4/site-lisp:/usr/share/emacs/site-lisp
 --with-x --with-xim --with-sound --with-xpm --with-jpeg --with-tiff
 --with-gif --with-png --with-rsvg --with-dbus --with-webp --with-xft
 --with-imagemagick --without-gpm --with-x-toolkit=gtk3 --with-pgtk
 --with-toolkit-scroll-bars --x-includes=/usr/include
 --x-libraries=/usr/lib64 --with-libotf --with-m17n-flt --with-cairo
 --with-xwidgets --build=x86_64-suse-linux --with-dumping=pdumper
 'CFLAGS=-O2 -Wall -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3
 -fstack-protector-strong -funwind-tables -fasynchronous-unwind-tables
 -fstack-clash-protection -Werror=return-type -flto=auto -g
 -D_GNU_SOURCE -DGDK_DISABLE_DEPRECATION_WARNINGS
 -DGLIB_DISABLE_DEPRECATION_WARNINGS -pipe -Wno-pointer-sign
 -Wno-unused-variable -Wno-unused-label -fno-optimize-sibling-calls
 -DPDMP_BASE='\''"emacs-wayland"'\''' LDFLAGS=-Wl,-O2'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ
IMAGEMAGICK JPEG JSON LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 MODULES
NATIVE_COMP NOTIFY INOTIFY PDUMPER PGTK PNG RSVG SECCOMP SOUND SQLITE3
THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XIM XWIDGETS GTK3 ZLIB

Important settings:
  value of $LC_NUMERIC: POSIX
  value of $LC_TIME: en_US.UTF-8
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Info

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  isearch-fold-quotes-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  buffer-read-only: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr info emacsbug message mailcap yank-media puny
dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg
rfc6068 epg-config gnus-util text-property-search time-date mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils comp
comp-cstr warnings icons subr-x rx cl-seq cl-macs gv cl-extra help-mode
cl-loaddefs cl-lib bytecomp byte-compile ispell rmc delsel lpr
easy-mmode pcase iso-transl tooltip cconv eldoc paren electric uniquify
ediff-hook vc-hooks lisp-float-type elisp-mode mwheel term/pgtk-win
pgtk-win term/common-win pgtk-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list replace newcomment text-mode lisp-mode prog-mode
register page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads xwidget-internal dbusbind inotify dynamic-setting
system-font-setting font-render-setting cairo gtk pgtk lcms2 multi-tty
make-network-process native-compile emacs)

Memory information:
((conses 16 101816 9593)
 (symbols 48 7600 0)
 (strings 32 23316 1856)
 (string-bytes 1 792835)
 (vectors 16 16145)
 (vector-slots 8 336083 17636)
 (floats 8 31 20)
 (intervals 56 4892 0)
 (buffers 984 12))

bug#74844: m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

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

> However, the @direntry as
> noted in the "dir" and "m-buffer-doc.info" files is "* m-buffer.doc."

Hmm... yup.
I pushed to Emacs a fix for the generation of that Texinfo element in
`ox-texinfo.el` and to `m-buffer` I pushed another change which tries to
workaround that bug (for when it's used with an older Emacs).

The patch for `ox-texinfo.el` is below.  It's "obviously safe", but
I suspect it's too late for Emacs-30.  Eli?


        Stefan


diff --git a/lisp/org/ox-texinfo.el b/lisp/org/ox-texinfo.el
index 6adee9fca3f..deceeca8947 100644
--- a/lisp/org/ox-texinfo.el
+++ b/lisp/org/ox-texinfo.el
@@ -826,9 +826,7 @@ org-texinfo-template
               ;; `dn' is presumed to be just the DIRNAME part, so generate
               ;; either `* DIRNAME: (FILENAME).' or `* FILENAME.', whichever
               ;; is shortest.
-              ((and dn (not (equal dn file)))
-               (format "* %s: (%s)." dn (or file dn)))
-              (t (format "* %s." file)))))
+              (t (format "* %s: (%s)." (or dn file) (or file dn))))))
        (concat "@dircategory " dircat "\n"
 	       "@direntry\n"
 	       (let ((dirdesc

bug#74844: m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

[Eli Zaretskii]

> Cc: 74844@debbugs.gnu.org
> Date: Fri, 13 Dec 2024 16:50:02 -0500
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> > However, the @direntry as
> > noted in the "dir" and "m-buffer-doc.info" files is "* m-buffer.doc."
> 
> Hmm... yup.
> I pushed to Emacs a fix for the generation of that Texinfo element in
> `ox-texinfo.el` and to `m-buffer` I pushed another change which tries to
> workaround that bug (for when it's used with an older Emacs).
> 
> The patch for `ox-texinfo.el` is below.  It's "obviously safe", but
> I suspect it's too late for Emacs-30.  Eli?

Maybe.  For now, I don't think I understand the fix.  What is 'dn' in
this snippet?  The command above says something (which need to be
fixed to follow the code change, btw), but I'm not sure it is accurate
or complete.

An entry in DIR can be either

     * TITLE: (FILE).           DESCRIPTION
or
     * TITLE: (FILE)NODE.       DESCRIPTION

What is 'dn' in the above scheme?  And what is 'file'?

P.S. Should we CC the Org folks on this discussion?

bug#74844: m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

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

>> > However, the @direntry as
>> > noted in the "dir" and "m-buffer-doc.info" files is "* m-buffer.doc."
>> 
>> Hmm... yup.
>> I pushed to Emacs a fix for the generation of that Texinfo element in
>> `ox-texinfo.el` and to `m-buffer` I pushed another change which tries to
>> workaround that bug (for when it's used with an older Emacs).
>> 
>> The patch for `ox-texinfo.el` is below.  It's "obviously safe", but
>> I suspect it's too late for Emacs-30.  Eli?
>
> Maybe.  For now, I don't think I understand the fix.  What is 'dn' in
> this snippet?  The command above says something (which need to be
> fixed to follow the code change, btw), but I'm not sure it is accurate
> or complete.
>
> An entry in DIR can be either
>
>      * TITLE: (FILE).           DESCRIPTION
> or
>      * TITLE: (FILE)NODE.       DESCRIPTION

[ Side question: Where is this documented?  ]

> What is 'dn' in the above scheme?  And what is 'file'?

`dn` is your TITLE and `file` is your FILE.

> P.S. Should we CC the Org folks on this discussion?

Duh, forgot about that, I just added Ihor, thanks,


        Stefan

bug#74844: m-buffer: Broken Top Directory node in Info manual due to malformed Texinfo direntry

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: suhailsingh247@gmail.com,  74844@debbugs.gnu.org, Ihor Radchenko
>  <yantar92@posteo.net>
> Date: Sat, 14 Dec 2024 08:53:04 -0500
> 
> >> > However, the @direntry as
> >> > noted in the "dir" and "m-buffer-doc.info" files is "* m-buffer.doc."
> >> 
> >> Hmm... yup.
> >> I pushed to Emacs a fix for the generation of that Texinfo element in
> >> `ox-texinfo.el` and to `m-buffer` I pushed another change which tries to
> >> workaround that bug (for when it's used with an older Emacs).
> >> 
> >> The patch for `ox-texinfo.el` is below.  It's "obviously safe", but
> >> I suspect it's too late for Emacs-30.  Eli?
> >
> > Maybe.  For now, I don't think I understand the fix.  What is 'dn' in
> > this snippet?  The command above says something (which need to be
> > fixed to follow the code change, btw), but I'm not sure it is accurate
> > or complete.
> >
> > An entry in DIR can be either
> >
> >      * TITLE: (FILE).           DESCRIPTION
> > or
> >      * TITLE: (FILE)NODE.       DESCRIPTION
> 
> [ Side question: Where is this documented?  ]

In the Texinfo manual, in the node "Menu Parts" (since the DIR file is
just a giant menu).

> > What is 'dn' in the above scheme?  And what is 'file'?
> 
> `dn` is your TITLE and `file` is your FILE.

Then I'm not sure this is correct:

+              (t (format "* %s: (%s)." (or dn file) (or file dn))))))

What if FILE is nil?  Can it be nil at this point?  The part in the
parentheses _must_ identify an Info file, with or without a node.  It
cannot be the TITLE, because that one can be arbitrary text.

The change is simple, so once we agree that it cannot do the wrong
thing, installing on emacs-30 is fine by me, assuming Ihor doesn't
object.