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

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: suhailsingh247@gmail.com,  74844@debbugs.gnu.org,  yantar92@posteo.net
> Date: Sat, 14 Dec 2024 16:05:34 -0500
> 
> >> > 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).
> 
> That says:
> 
>     A menu entry has three parts, only the second of which is required:
>     
>         The menu entry name (optional).
>         The name of the node (required).
>         A description of the item (optional). 
> 
> It's not clear what "optional" means for the menu entry name: how do we
> write without it?

Like this:

 * (FILE)NODE.

> Does it refer to the
> 
>     * NAME::
> 
> syntax described in the next node?

That stands for

  * NAME: NAME.

So you could also write

  * (FILE)NODE::

> BTW, that next node says that `* NAME::` is equivalent to:
> 
>     * NAME: NAME.
> 
> but shouldn't that be
> 
>     * NAME: (NAME).
> 
> ?

No, because NAME here is the name of a node, and in DIR all the nodes
are in other files, so NAME should look like "(FILE)NODE" or "(FILE)"
(which stands for "(FILE)Top").  If NAME is a node in the same file as
the menu, the (FILE) part can be omitted.

> The manual reads like a "user manual" and I think I need something more
> like a "reference manual", or a specification, with a precise grammar.

That's because arbitrary programs are not supposed to generate Info
formats, they are supposed to invoke Texinfo programs to do that.  For
example, to update DIR, you are supposed to invoke install-info, which
knows about all these rules (and more).

> > Then I'm not sure this is correct:
> >
> > +              (t (format "* %s: (%s)." (or dn file) (or file dn))))))
> >
> > What if FILE is nil?
> 
> My reading of the code says it *may* potentially be nil in some corner
> case, but I have no idea how that could happen.  A nil value for `dn` is
> normal, in contrast.

A nil value for 'dn' is okay, it produces a correct entry.

> > 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.
> 
> If FILE is nil, we're in trouble.  IIRC the `(or file dn)` in the code
> just tried to preserve the previous behavior in the unlikely case that
> FILE is nil, for lack of understanding about when (or even if) that
> can happen.

In that case, I suggest the following code:

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

That is, the bug in the original code is that they failed to put FILE
in parentheses (and also wanted a premature optimization of producing
the "shortest" entry).  This assumes that FILE does not include
parentheses and does not specify a node, i.e. it is NOT in the form
"(FILE)NODE".  My reading of ox-texinfo.el is that if that could
happen, the code in org-texinfo-template is already in trouble,
because it is obviously not ready for that.

WDYT?