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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 15 Dec 2024 20:23:24 +0200

> From: Suhail Singh <[email-masked]>
> Cc: Suhail Singh <[email-masked]>,  [email-masked],
>   [email-masked],  [email-masked]
> Date: Sun, 15 Dec 2024 12:53:01 -0500
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> Btw, based on my interpretation of the Org manual
> >> (info "(org) Texinfo specific export settings"), I would've expected the
> >> below to work:
> >> 
> >> #+begin_src diff
> >>   -#+TEXINFO_DIR_TITLE: m-buffer-doc
> >>   -#+TEXINFO_DIR_DESC: Manipulate the Contents of Emacs Buffers
> >>   +#+TEXINFO_FILENAME: m-buffer-doc.texi
> >>   +#+TEXINFO_DIR_NAME: m-buffer
> >> #+end_src
> >
> > Why do you suggest removing TEXINFO_DIR_TITLE
> 
> Because of this comment in ox-texinfo.el which suggests that it is
> obsolete:

FWIW, I disagree with that decision of Org folks.

> > and TEXINFO_DIR_DESC?
> 
> Per (info "(org) Texinfo specific export settings"):
> 
> #+begin_quote
>   ‘TEXINFO_DIR_DESC’
>        The directory description of the document.  Defaults to the title
>        of the document.
> #+end_quote
> 
> The Org document in question already has a TITLE specified.

That there is a default does not mean that we need to discard the
description when we do have it.  Discarding it loses important
information (which programs like install-info use).

> > And why is TEXINFO_FILENAME important?
> 
> Per (info "(org) Texinfo specific export settings"):
> 
> #+begin_quote
>   ‘TEXINFO_FILENAME’
>        The Texinfo filename.
> #+end_quote

Why is this important?

> Also,
> 
> #+begin_quote
>   ‘TEXINFO_DIR_NAME’
>        The directory name of the document.  This is the short name under
>        which the ‘m’ command will find your manual in the main Info
>        directory.  It defaults to the base name of the Texinfo file.
> 
>        The full form of the Texinfo entry is ‘* DIRNAME: NODE.’ where
>        ‘NODE’ is usually just ‘(FILENAME)’.  Normally this option only
>        provides the ‘DIRNAME’ part, but if you need more control, it can
>        also be the full entry (recognized by the presence of parentheses
>        or a leading ~* ~).
> #+end_quote
> 
> I interpreted "FILENAME" above to mean TEXINFO_FILENAME, which is also
> what's suggested by the code:
> 
> #+begin_src emacs-lisp
> 	    (file (or (org-strip-quotes (plist-get info :texinfo-filename))
> 		    (plist-get info :output-file)))
> #+end_src

This is a wrong interpretation.  FILENAME here is the Info file name,
not the Texinfo file name (the latter is the file name of the Texinfo
source).