bug#2975: `texinfo-master-menu' doesn't work.

[Eli Zaretskii]

> Date: Sun, 11 Dec 2011 17:38:59 +0000
> Cc: bug-texinfo@gnu.org, 2975-done@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > "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.

Correct.  And now the current doc string:

    "Make a master menu for a whole Texinfo file.
  Remove pre-existing master menu, if there is one.

  This function supports only single-file manuals.  For multi-file
  manuals, use `texinfo-multiple-files-update'.

  This function creates or updates the @detailmenu section of a
  master menu that follows the Top node.  It replaces any existing
  detailed menu that follows the top node.  The detailed menu
  includes every entry from all the other menus.  By default, the
  existing menus, including the menu in the Top node, are not
  updated according to the buffer contents, so all the menus should
  be updated first using `texinfo-make-menu' or
  `texinfo-all-menus-update', which see.  Alternatively, invoke
  this function with a prefix argument, see below.

  Non-nil, non-numeric argument (C-u prefix, if interactive) means
  first update all existing menus in the buffer (incorporating
  descriptions from pre-existing menus) before it constructs the
  master menu.  If the argument is numeric (e.g., \"C-u 2\"),
  update all existing nodes as well, by calling
  \`texinfo-update-node' on the entire file.  Warning: do NOT
  invoke with a numeric argument if your Texinfo file uses @node
  lines without the `Next', `Previous', `Up' pointers, as the
  result could be an invalid Texinfo file!

  The function removes and recreates the detailed part of an already
  existing master menu.  This action assumes that the pre-existing
  master menu uses the standard `texinfo-master-menu-header' for the
  detailed menu.

  The master menu has the following format, which is adapted from the
  recommendation in the Texinfo Manual:

     * The first part contains the major nodes in the Texinfo file: the
       nodes for the chapters, chapter-like sections, and the major
       appendices.  This includes the indices, so long as they are in
       chapter-like sections, such as unnumbered sections.

     * The second and subsequent parts contain a listing of the other,
       lower level menus, in order.  This way, an inquirer can go
       directly to a particular node if he or she is searching for
       specific information.

  Each of the menus in the detailed node listing is introduced by the
  title of the section containing the menu.

> @dfn{master menu} is on page "Master Menu Parts" in the Texinfo manual.
> In particular,
> 
>     A master menu is enclosed in `@menu' and `@end menu' commands ...

I didn't do anything with the Texinfo manual, mind you.  This bug
report is about Emacs.

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

I'm just guessing here, but my guess is that you sometimes may wish to
create or update only the @detailmenu.  After all, texinfo-make-menu
is the way to create/update any menu, including the top-level menu, if
you don't have one or if it is outdated.

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

It sounds like your notion of "master menu" is different from what the
command means, see above.

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

Feel free to suggest specific improvements or point out specific
parts of the doc string that need improvement.