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

[Alan Mackenzie <acm@muc.de>]

Hello again, Eli.

On Sun, Dec 11, 2011 at 08:18:06PM +0200, Eli Zaretskii wrote:
> > 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.

Although I updated and rebuilt Emacs yesterday, I got the old doc string,
so please forgive my reply.  The way I got this doc string was:

    emacs -Q
    M-x load-library texinfo
    C-h f texinfo-master-menu

.  It turns out that the doc string is duplicated in texinfo.el in an
autoload form.  ;-(

[ .... ]

> 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

Correction: "before CONSTRUCTING the master menu."

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

:-)  There's an inconsistency there.  The manual is Karl B's thing, isn't
it?

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

[ .... ]

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

THAT is the thing that's caused this discussion.  I have conceptualised
"master menu" as the entire hierarchical thing starting at Top.  You have
seen a separate menu in each node (including Top) and then @detailedmenu
as a summary, a distinct entity.  Now everything is clear.

-- 
Alan Mackenzie (Nuremberg, Germany).