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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 15 Dec 2024 16:00:06 +0200

> From: Stefan Monnier <[email-masked]>
> Cc: [email-masked],  [email-masked],  [email-masked]
> Date: Sun, 15 Dec 2024 08:38:02 -0500
> 
> >> 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.

That's true, but we are discussing what ox-texinfo.el does, or at
least so I thought?  There's no @direntry there, only parts of it
stashes as property lists on some symbols (according to a quick glance
I had at the functions where this code resides).

> [ 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.  🙂  ]

Feel free to take this up with the Texinfo developers.

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

So will you install that?