Re: `texinfo-master-menu' doesn't work.

[Alan Mackenzie]

Hello, Eli!

On Sat, Dec 10, 2011 at 02:40:39PM +0200, Eli Zaretskii wrote:
> > Date: Sun, 12 Apr 2009 21:33:40 +0000
> > From: Alan Mackenzie <address@hidden>

> > In Emacs, either 22.3 or a recent CVS version ...
> > emacs -Q

> > 1.

> > (i) C-c C-f .../path/to/emacs/doc/misc/cc-mode.texi
> > (ii) M-g M-g 238          ; the second line of the menu,
> >                           ; contents "* Overview::"
> > (ii) C-k C-k              ; Kill this line

> > (v) Now do C-c C-u m.  This flashes the screen and reports
> > "Done...completed making master menu.  You may save the buffer.".
> > However, it hasn't made the master menu - the "* Overview::" line is
> > still missing.

> "C-c C-u m" (texinfo-master-menu) is not supposed to update the menus
> in the buffer, including the menu in the Top node, unless you invoke
> it with a prefix argument.  If you don't invoke it with a prefix arg,
> you need to update the menus yourself, either manually or by running
> texinfo-make-menu or texinfo-all-menus-update.  This is because this
> command only looks at the _existing_ menus; it does NOT look at the
> @node lines to recreate or update any missing/outdated entries in
> those menus.

> I made this clear in the doc string of texinfo-master-menu.

Sorry, I find it anything but clear.  I think I've finally twigged what
C-c C-u m does.  It creates or updates the @detailmenu part of the master
menu.  Please correct me if I'm wrong about this.  However, it doesn't
create/update the first part of the master menu, and nor does it create
the @detailmenu if @menu is missing.

@dfn{master menu} is on page "Master Menu Parts" in the Texinfo manual.
In particular,

    A master menu is enclosed in address@hidden' and address@hidden menu' 
commands ...

Why doesn't C-c C-u m update the entire master menu?  I mean, what use is
the current command, as opposed to the one I want?

> > 2.

> > (i) Kill (remove) the entire master menu from the buffer (between the
> >   lines "@menu" and "@end menu").

> > (ii) Try to regenerate the master menu with C-c C-u m.  This signals the
> > puzzling error "Buffer lacks ordinary `Top' menu in which to insert
> > master".  It is not clear what a "`Top' menu" is, in what respect it is
> > "ordinary", and in what regard the new master menu is inserted into it.
> > The existing master menu was not contained within any menu.

> The error is signaled because texinfo-master-menu does not update or
> create any menus, see above.

t-m-m's doc string states explicitly that it DOES make a master menu.

> By deleting the menu in the Top node, you removed the part of the
> buffer on which texinfo-master-menu depends for doing its job.  So it
> barfed.

I think there's a mismatch between the command and its doc string.  The
doc string says "make a master menu", not merely the insides of one.

> I changed the error message text so it is hopefully more clear.  It
> now says:

>   Buffer lacks a menu in its first node; create it, then run me again

OK.

> > 3.

[ .... ]

> > There is no verb in "texinfo master menu", so one is led by intelligent
> > guessing to believe that the command does whatever necessary to insert
> > or update the master menu.  This doesn't happen.

> The crucial part of the doc string was this:

>   The master menu includes every entry from all the other menus.

Ah.  My understanding of that was a strict "includes", as distinct from a
"consists of".  The first part of the master menu remains uncreated.

> IOW, it only collects entries from existing menus, it does NOT update
> the menus.  Admittedly, this crucial piece of information was buried
> deep in the doc string.  Hopefully, now it is more clear.

I think I've understood now, but I don't think it's at all clear.

> All of the above changes are in revision 106651 on the trunk.

I've got that.

> I'm closing this bug report.

Hmmm.  I'm not entirely happy about that.

I can't help feeling that there's some specific word or phrase which I've
misunderstood, and this isn't clear to either of us.  In the mean time,
C-c C-u m, without a prefix, seems to me to be a command of limited
utility.

> Sorry for the long delay in handling it.

No problem!

-- 
Alan Mackenzie (Nuremberg, Germany).