From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#2975: `texinfo-master-menu' doesn't work. Date: Sun, 11 Dec 2011 20:18:06 +0200 Message-ID: <83mxazkm5d.fsf@gnu.org> References: <20090412213340.GA3615@muc.de> <837h24mwfs.fsf@gnu.org> <20111211173859.GA2755@acm.acm> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1323627546 9251 80.91.229.12 (11 Dec 2011 18:19:06 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 11 Dec 2011 18:19:06 +0000 (UTC) Cc: 2975@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Dec 11 19:19:01 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 1RZnzI-0000Hn-A4 for geb-bug-gnu-emacs@m.gmane.org; Sun, 11 Dec 2011 19:19:00 +0100 Original-Received: from localhost ([::1]:38968 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RZnzH-0003OF-E3 for geb-bug-gnu-emacs@m.gmane.org; Sun, 11 Dec 2011 13:18:59 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:60359) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RZnzE-0003O7-K6 for bug-gnu-emacs@gnu.org; Sun, 11 Dec 2011 13:18:57 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RZnzC-0000UL-TV for bug-gnu-emacs@gnu.org; Sun, 11 Dec 2011 13:18:56 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:33787) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RZnzC-0000UH-Ru for bug-gnu-emacs@gnu.org; Sun, 11 Dec 2011 13:18:54 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1RZo0H-0000Rq-UN for bug-gnu-emacs@gnu.org; Sun, 11 Dec 2011 13:20:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 11 Dec 2011 18:20: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.13236275611666 (code B ref 2975); Sun, 11 Dec 2011 18:20:01 +0000 Original-Received: (at 2975) by debbugs.gnu.org; 11 Dec 2011 18:19:21 +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 1RZnzc-0000Qp-Te for submit@debbugs.gnu.org; Sun, 11 Dec 2011 13:19:21 -0500 Original-Received: from mtaout22.012.net.il ([80.179.55.172]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1RZnzZ-0000Qg-Ha for 2975@debbugs.gnu.org; Sun, 11 Dec 2011 13:19:19 -0500 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0LW100E00XGT9K00@a-mtaout22.012.net.il> for 2975@debbugs.gnu.org; Sun, 11 Dec 2011 20:18:08 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([77.124.128.192]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LW1006N4XI4F7W1@a-mtaout22.012.net.il>; Sun, 11 Dec 2011 20:18:08 +0200 (IST) In-reply-to: <20111211173859.GA2755@acm.acm> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sun, 11 Dec 2011 13:20: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:54895 Archived-At: > 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. > > 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.