From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#2975: `texinfo-master-menu' doesn't work. Date: Mon, 12 Dec 2011 12:25:44 +0000 Message-ID: <20111212122544.GA2910@acm.acm> References: <20090412213340.GA3615@muc.de> <837h24mwfs.fsf@gnu.org> <20111211173859.GA2755@acm.acm> <83mxazkm5d.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1323693125 28014 80.91.229.12 (12 Dec 2011 12:32:05 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 12 Dec 2011 12:32:05 +0000 (UTC) Cc: 2975@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Dec 12 13:31:58 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Ra52z-0005l5-Lh for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Dec 2011 13:31:57 +0100 Original-Received: from localhost ([::1]:55862 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ra52z-0006II-4F for geb-bug-gnu-emacs@m.gmane.org; Mon, 12 Dec 2011 07:31:57 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:55862) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ra52w-0006ID-Jq for bug-gnu-emacs@gnu.org; Mon, 12 Dec 2011 07:31:55 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ra52s-0000Pz-C9 for bug-gnu-emacs@gnu.org; Mon, 12 Dec 2011 07:31:54 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:34225) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ra52s-0000Pu-7C for bug-gnu-emacs@gnu.org; Mon, 12 Dec 2011 07:31:50 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1Ra541-0000EU-QO for bug-gnu-emacs@gnu.org; Mon, 12 Dec 2011 07:33:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 12 Dec 2011 12:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 2975 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 2975-submit@debbugs.gnu.org id=B2975.1323693177882 (code B ref 2975); Mon, 12 Dec 2011 12:33:01 +0000 Original-Received: (at 2975) by debbugs.gnu.org; 12 Dec 2011 12:32:57 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ra53x-0000EB-DJ for submit@debbugs.gnu.org; Mon, 12 Dec 2011 07:32:57 -0500 Original-Received: from colin.muc.de ([193.149.48.1] helo=mail.muc.de) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ra53u-0000Dz-GG for 2975@debbugs.gnu.org; Mon, 12 Dec 2011 07:32:56 -0500 Original-Received: (qmail 6269 invoked by uid 3782); 12 Dec 2011 12:31:41 -0000 Original-Received: from acm.muc.de (pD9556F26.dip.t-dialin.net [217.85.111.38]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 12 Dec 2011 13:31:39 +0100 Original-Received: (qmail 2982 invoked by uid 1000); 12 Dec 2011 12:25:44 -0000 Content-Disposition: inline In-Reply-To: <83mxazkm5d.fsf@gnu.org> User-Agent: Mutt/1.5.21 (2010-09-15) X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Mon, 12 Dec 2011 07:33:01 -0500 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:54902 Archived-At: 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 > > > "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).