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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 10 Dec 2011 14:40:39 +0200

> Date: Sun, 12 Apr 2009 21:33:40 +0000
> From: Alan Mackenzie <[email-masked]>
> 
> 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.

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

> 3.
> 
> (i) C-c C-f .../path/to/emacs/doc/lispref/elisp.texi
> (ii) M-g M-g 108       ; the second line of the menu,
>                        ; "* Lisp Data Types:: ...."
> (iii) C-k C-k          ; Kill this line
> 
> (iv) Now do C-c C-u m.  This doesn't regenerate the master menu.
> Instead, it deletes the @detailmenu without restoring the "* Lisp Data
> Types::" line.

texinfo-master-menu does not support multi-file manuals (which is what
elisp.texi is).  For that, one should use
texinfo-multiple-files-update.  I made that clear in the doc string.

> Neither the doc string for `texinfo-master-menu' nor the texinfo manual
> (page "Updating Nodes and Menus") describe other than vaguely what this
> command is supposed to do.

I made that more clear in the commentary at the beginning of
texnfo-upd.el and in the doc string of texinfo-master-menu.

> The doc string states, accurately, that
> 
>     The function removes the detailed part of an already existing master
>     menu.
> 
> , which though accurate, is puzzling in the extreme; what one wants from
> this command is for the detailed bit to be inserted, not deleted.
> 
> 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.

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.

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

I'm closing this bug report.  Sorry for the long delay in handling it.