Package: emacs;
Reported by: Alan Mackenzie <acm <at> muc.de>
Date: Sun, 12 Apr 2009 21:40:06 UTC
Severity: normal
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Message #74 received at 2975 <at> debbugs.gnu.org (full text, mbox):
From: Alan Mackenzie <acm <at> muc.de> To: Eli Zaretskii <eliz <at> gnu.org> Cc: 2975 <at> debbugs.gnu.org Subject: Re: `texinfo-master-menu' doesn't work. Date: Mon, 12 Dec 2011 12:25:44 +0000
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 <at> gnu.org, 2975-done <at> debbugs.gnu.org
> > From: Alan Mackenzie <acm <at> 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).
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.