bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 7 Dec 2011 15:19:59 -0600
> From: "Roland Winkler" <winkler@gnu.org>
> Cc: 2975@debbugs.gnu.org
> 
> On Wed Dec 7 2011 Stefan Monnier wrote:
> > I'm pretty sure texinfo-master-menu is not used for that, indeed.
> > I think "update all menus" is the more common helper command.
> > 
> > IIRC it also suffered from problems where it adds data to "Node"s which
> > should better not be added at all, so makeinfo can auto-fill it for you
> > (and makeinfo actually complains about what texinfo-master-menu puts
> > there).
> 
> I am not sure I understand what you say about nodes.

What Stefan says is that the form of @node produced by
texinfo-master-menu (when it is invoked on a region and/or with a
prefix argument) includes the Next, Prev, and Up pointers, even if the
original file didn't have those pointers.  Worse, due to incomplete
support of the more advanced Texinfo features, the produced pointers
can cause makeinfo barf.  IOW, the command could potentially take a
perfectly valid Texinfo file and produce an invalid one.

The node pointers thingy is particularly baaad because makeinfo
doesn't actually need these pointers, if your Texinfo files are
structured using a few simple rules, documented in the Texinfo manual,
see "texinfo(makeinfo Pointer Creation)".

If you keep your Texinfo structured according to these rules, there's
no need for Next, Prev, and Up pointers on the @node lines; makeinfo
will compute them automatically.

By forcibly inserting these pointers, texinfo-master-menu prevents you
from using this very convenient feature: you are forced to maintain
these pointers whenever you insert or delete nodes.

> I started this thread because
> 
> > The texinfo manual says about "Updating Nodes and Menus"
> > 
> >   If you do not use the updating commands, you need to write menus
> >   and node pointers by hand, which is a tedious task.
> 
> Is there any emacs command that can help reliably for updating the nodes?
> (Nodes appear to get screwed up by texinfo-master-menu.)

Well, see above: you don't need to be bothered by that, if you adhere
to the rules explained in the Texinfo manual.

> Of course, I believe that makeinfo can add the info about the node
> pointers. But what about output formats not supported by makeinfo?
> I believe that something like TeX needs them.

TeX doesn't need them.  These pointers are there to allow traversing
the on-line manual, and are not needed for non on-line versions.

> > Maybe the better course here is to deprecate it, seeing how noone seems
> > interested in fixing it (if it can be fixed).

Define "fixed".  Which of the current misfeatures are urgent to fix?

> This would certainly help at least somewhat to clarify the
> situation.

See my other mail (which I didn't write yet ;-) about "the situation".