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

[Stefan Monnier]

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

`@direntry` contains text in the Info format and is not generated by
those tools, hence the need for Texinfo *users* to know about that part
of the Info format.

[ Also the Info format is manipulated by enough tools that a reference
  manual would not be amiss, even if it's used only "internally" by all
  these tools.  🙂  ]

> In that case, I suggest the following code:
>
>    (dn
>      (format "* %s: (%s)." dn (or file dn)))
>    (t (format "* (%s)." file))

Sounds good to me.

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

That's right.


        Stefan