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

[Stefan Monnier]

>> > 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?  Does it refer to the

    * NAME::

syntax described in the next node?
BTW, that next node says that `* NAME::` is equivalent to:

    * NAME: NAME.

but shouldn't that be

    * NAME: (NAME).

?

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.

>> > 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?

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.

> 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.


        Stefan