* bug#2975: `texinfo-master-menu' doesn't work. @ 2009-04-12 21:33 Alan Mackenzie 2011-12-10 12:40 ` Eli Zaretskii [not found] ` <837h24mwfs.fsf@gnu.org> 0 siblings, 2 replies; 24+ messages in thread From: Alan Mackenzie @ 2009-04-12 21:33 UTC (permalink / raw) To: bug-texinfo, bug-gnu-emacs In Emacs, either 22.3 or a recent CVS version ... emacs -Q 1. (i) C-c C-f .../path/to/emacs/doc/misc/cc-mode.texi (ii) M-g M-g 238 ; the second line of the menu, ; contents "* Overview::" (ii) C-k C-k ; Kill this line (v) Now do C-c C-u m. This flashes the screen and reports "Done...completed making master menu. You may save the buffer.". However, it hasn't made the master menu - the "* Overview::" line is still missing. ######################################################################## 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. ######################################################################### 3. (i) C-c C-f .../path/to/emacs/doc/lispref/elisp.texi (ii) M-g M-g 108 ; the second line of the menu, ; "* Lisp Data Types:: ...." (iii) C-k C-k ; Kill this line (iv) Now do C-c C-u m. This doesn't regenerate the master menu. Instead, it deletes the @detailmenu without restoring the "* Lisp Data Types::" line. ######################################################################### Comments: Neither the doc string for `texinfo-master-menu' nor the texinfo manual (page "Updating Nodes and Menus") describe other than vaguely what this command is supposed to do. The doc string states, accurately, that The function removes the detailed part of an already existing master menu. , which though accurate, is puzzling in the extreme; what one wants from this command is for the detailed bit to be inserted, not deleted. There is no verb in "texinfo master menu", so one is led by intelligent guessing to believe that the command does whatever necessary to insert or update the master menu. This doesn't happen. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: `texinfo-master-menu' doesn't work. 2009-04-12 21:33 bug#2975: `texinfo-master-menu' doesn't work Alan Mackenzie @ 2011-12-10 12:40 ` Eli Zaretskii [not found] ` <837h24mwfs.fsf@gnu.org> 1 sibling, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-10 12:40 UTC (permalink / raw) To: Alan Mackenzie; +Cc: bug-texinfo, 2975-done > Date: Sun, 12 Apr 2009 21:33:40 +0000 > From: Alan Mackenzie <acm@muc.de> > > In Emacs, either 22.3 or a recent CVS version ... > emacs -Q > > 1. > > (i) C-c C-f .../path/to/emacs/doc/misc/cc-mode.texi > (ii) M-g M-g 238 ; the second line of the menu, > ; contents "* Overview::" > (ii) C-k C-k ; Kill this line > > (v) Now do C-c C-u m. This flashes the screen and reports > "Done...completed making master menu. You may save the buffer.". > However, it hasn't made the master menu - the "* Overview::" line is > still missing. "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. > 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. By deleting the menu in the Top node, you removed the part of the buffer on which texinfo-master-menu depends for doing its job. So it barfed. I changed the error message text so it is hopefully more clear. It now says: Buffer lacks a menu in its first node; create it, then run me again > 3. > > (i) C-c C-f .../path/to/emacs/doc/lispref/elisp.texi > (ii) M-g M-g 108 ; the second line of the menu, > ; "* Lisp Data Types:: ...." > (iii) C-k C-k ; Kill this line > > (iv) Now do C-c C-u m. This doesn't regenerate the master menu. > Instead, it deletes the @detailmenu without restoring the "* Lisp Data > Types::" line. texinfo-master-menu does not support multi-file manuals (which is what elisp.texi is). For that, one should use texinfo-multiple-files-update. I made that clear in the doc string. > Neither the doc string for `texinfo-master-menu' nor the texinfo manual > (page "Updating Nodes and Menus") describe other than vaguely what this > command is supposed to do. I made that more clear in the commentary at the beginning of texnfo-upd.el and in the doc string of texinfo-master-menu. > The doc string states, accurately, that > > The function removes the detailed part of an already existing master > menu. > > , which though accurate, is puzzling in the extreme; what one wants from > this command is for the detailed bit to be inserted, not deleted. > > There is no verb in "texinfo master menu", so one is led by intelligent > guessing to believe that the command does whatever necessary to insert > or update the master menu. This doesn't happen. The crucial part of the doc string was this: The master menu includes every entry from all the other menus. 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. All of the above changes are in revision 106651 on the trunk. I'm closing this bug report. Sorry for the long delay in handling it. ^ permalink raw reply [flat|nested] 24+ messages in thread
[parent not found: <837h24mwfs.fsf@gnu.org>]
[parent not found: <20111211173859.GA2755@acm.acm>]
* bug#2975: `texinfo-master-menu' doesn't work. [not found] ` <20111211173859.GA2755@acm.acm> @ 2011-12-11 18:18 ` Eli Zaretskii 2011-12-12 12:25 ` Alan Mackenzie 0 siblings, 1 reply; 24+ messages in thread From: Eli Zaretskii @ 2011-12-11 18:18 UTC (permalink / raw) To: Alan Mackenzie; +Cc: 2975 > 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: `texinfo-master-menu' doesn't work. 2011-12-11 18:18 ` Eli Zaretskii @ 2011-12-12 12:25 ` Alan Mackenzie 2011-12-12 13:02 ` Eli Zaretskii 0 siblings, 1 reply; 24+ messages in thread From: Alan Mackenzie @ 2011-12-12 12:25 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 2975 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). ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: `texinfo-master-menu' doesn't work. 2011-12-12 12:25 ` Alan Mackenzie @ 2011-12-12 13:02 ` Eli Zaretskii 0 siblings, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-12 13:02 UTC (permalink / raw) To: Alan Mackenzie; +Cc: 2975 > Date: Mon, 12 Dec 2011 12:25:44 +0000 > Cc: 2975@debbugs.gnu.org > From: Alan Mackenzie <acm@muc.de> > > > 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. Does the new doc string make this clear, or do you still see place for improvement? Thanks. ^ permalink raw reply [flat|nested] 24+ messages in thread
[parent not found: <20191.12232.556454.551166@gargle.gargle.HOWL>]
[parent not found: <E1RYHPD-0000vm-PC@fencepost.gnu.org>]
[parent not found: <h87h28tgcg.fsf@fencepost.gnu.org>]
[parent not found: <20191.48632.665251.448872@gargle.gargle.HOWL>]
* bug#2975: texinfo-master-menu and emacs.texi [not found] ` <20191.48632.665251.448872@gargle.gargle.HOWL> @ 2011-12-07 20:43 ` Stefan Monnier 2011-12-07 21:19 ` Roland Winkler 0 siblings, 1 reply; 24+ messages in thread From: Stefan Monnier @ 2011-12-07 20:43 UTC (permalink / raw) To: Roland Winkler; +Cc: 2975 > Thanks...Now I am yet more confused. I thought I look into > emacs.texi because I assumed that this info manual has been updated > continuously in recent years and this updating has been done with > the editor of my choice which is emacs. So what have people done who > contributed to the emacs info manual to work around these > difficulties? Which parts of emacs' texinfo support do what they are > supposed to do and which parts seem to be malfunctioning? I'm pretty sure texinfo-master-menu is not used for that, indeed. I think "update all menus" is the more common helper command. IIRC it also suffered from problems where it adds data to "Node"s which should better not be added at all, so makeinfo can auto-fill it for you (and makeinfo actually complains about what texinfo-master-menu puts there). Maybe the better course here is to deprecate it, seeing how noone seems interested in fixing it (if it can be fixed). Stefan ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-07 20:43 ` bug#2975: texinfo-master-menu and emacs.texi Stefan Monnier @ 2011-12-07 21:19 ` Roland Winkler 2011-12-08 6:17 ` Eli Zaretskii 0 siblings, 1 reply; 24+ messages in thread From: Roland Winkler @ 2011-12-07 21:19 UTC (permalink / raw) To: Stefan Monnier; +Cc: 2975 On Wed Dec 7 2011 Stefan Monnier wrote: > I'm pretty sure texinfo-master-menu is not used for that, indeed. > I think "update all menus" is the more common helper command. > > IIRC it also suffered from problems where it adds data to "Node"s which > should better not be added at all, so makeinfo can auto-fill it for you > (and makeinfo actually complains about what texinfo-master-menu puts > there). I am not sure I understand what you say about nodes. I started this thread because > The texinfo manual says about "Updating Nodes and Menus" > > If you do not use the updating commands, you need to write menus > and node pointers by hand, which is a tedious task. Is there any emacs command that can help reliably for updating the nodes? (Nodes appear to get screwed up by texinfo-master-menu.) Of course, I believe that makeinfo can add the info about the node pointers. But what about output formats not supported by makeinfo? I believe that something like TeX needs them. > Maybe the better course here is to deprecate it, seeing how noone seems > interested in fixing it (if it can be fixed). This would certainly help at least somewhat to clarify the situation. Roland ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-07 21:19 ` Roland Winkler @ 2011-12-08 6:17 ` Eli Zaretskii 2011-12-08 10:38 ` Štěpán Němec 0 siblings, 1 reply; 24+ messages in thread From: Eli Zaretskii @ 2011-12-08 6:17 UTC (permalink / raw) To: Roland Winkler; +Cc: 2975 > Date: Wed, 7 Dec 2011 15:19:59 -0600 > From: "Roland Winkler" <winkler@gnu.org> > Cc: 2975@debbugs.gnu.org > > On Wed Dec 7 2011 Stefan Monnier wrote: > > I'm pretty sure texinfo-master-menu is not used for that, indeed. > > I think "update all menus" is the more common helper command. > > > > IIRC it also suffered from problems where it adds data to "Node"s which > > should better not be added at all, so makeinfo can auto-fill it for you > > (and makeinfo actually complains about what texinfo-master-menu puts > > there). > > I am not sure I understand what you say about nodes. What Stefan says is that the form of @node produced by texinfo-master-menu (when it is invoked on a region and/or with a prefix argument) includes the Next, Prev, and Up pointers, even if the original file didn't have those pointers. Worse, due to incomplete support of the more advanced Texinfo features, the produced pointers can cause makeinfo barf. IOW, the command could potentially take a perfectly valid Texinfo file and produce an invalid one. The node pointers thingy is particularly baaad because makeinfo doesn't actually need these pointers, if your Texinfo files are structured using a few simple rules, documented in the Texinfo manual, see "texinfo(makeinfo Pointer Creation)". If you keep your Texinfo structured according to these rules, there's no need for Next, Prev, and Up pointers on the @node lines; makeinfo will compute them automatically. By forcibly inserting these pointers, texinfo-master-menu prevents you from using this very convenient feature: you are forced to maintain these pointers whenever you insert or delete nodes. > I started this thread because > > > The texinfo manual says about "Updating Nodes and Menus" > > > > If you do not use the updating commands, you need to write menus > > and node pointers by hand, which is a tedious task. > > Is there any emacs command that can help reliably for updating the nodes? > (Nodes appear to get screwed up by texinfo-master-menu.) Well, see above: you don't need to be bothered by that, if you adhere to the rules explained in the Texinfo manual. > Of course, I believe that makeinfo can add the info about the node > pointers. But what about output formats not supported by makeinfo? > I believe that something like TeX needs them. TeX doesn't need them. These pointers are there to allow traversing the on-line manual, and are not needed for non on-line versions. > > Maybe the better course here is to deprecate it, seeing how noone seems > > interested in fixing it (if it can be fixed). Define "fixed". Which of the current misfeatures are urgent to fix? > This would certainly help at least somewhat to clarify the > situation. See my other mail (which I didn't write yet ;-) about "the situation". ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 6:17 ` Eli Zaretskii @ 2011-12-08 10:38 ` Štěpán Němec 2011-12-08 12:20 ` Eli Zaretskii 0 siblings, 1 reply; 24+ messages in thread From: Štěpán Němec @ 2011-12-08 10:38 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Roland Winkler, 2975 On Thu, 08 Dec 2011 07:17:40 +0100 Eli Zaretskii wrote: >> > Maybe the better course here is to deprecate it, seeing how noone seems >> > interested in fixing it (if it can be fixed). > > Define "fixed". Which of the current misfeatures are urgent to fix? I'd say the fact that OT1H `texinfo-master-menu' is recommended as "the primary command" in the Texinfo manual (info "(texinfo)Updating Commands"), and OTOH it (sometimes?) breaks things, is a rather urgent-to-be-fixed misfeature. I've had this problem in the past, too, and had no idea what's going on until this came up now. I think it's very important that there is a clear recipe for maintaining Texinfo documentation which people not interested in the details or implementation of Texinfo (== the vast majority of Texinfo writers) can easily find and go by. -- Štěpán ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 10:38 ` Štěpán Němec @ 2011-12-08 12:20 ` Eli Zaretskii 2011-12-08 14:46 ` Stefan Monnier 2011-12-08 18:52 ` Roland Winkler 0 siblings, 2 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-08 12:20 UTC (permalink / raw) To: Štěpán Němec; +Cc: 2975, winkler, Karl Berry > From: Štěpán Němec <stepnem@gmail.com> > Cc: "Roland Winkler" <winkler@gnu.org>, 2975@debbugs.gnu.org > Date: Thu, 08 Dec 2011 11:38:01 +0100 > > On Thu, 08 Dec 2011 07:17:40 +0100 > Eli Zaretskii wrote: > > >> > Maybe the better course here is to deprecate it, seeing how noone seems > >> > interested in fixing it (if it can be fixed). > > > > Define "fixed". Which of the current misfeatures are urgent to fix? > > I'd say the fact that OT1H `texinfo-master-menu' is recommended as "the > primary command" in the Texinfo manual (info "(texinfo)Updating Commands"), > and OTOH it (sometimes?) breaks things, is a rather urgent-to-be-fixed > misfeature. The simplest fix would be to remove the updating of the @node lines. Would anyone object? Karl? > I think it's very important that there is a clear recipe for maintaining > Texinfo documentation which people not interested in the details or > implementation of Texinfo (== the vast majority of Texinfo writers) can > easily find and go by. That is a separate and non-trivial project. Texinfo Mode has a lot of commands, some of which cater to specific workflows and organizations of manuals. Making a coherent set of instructions for people who are "not interested in the details" is not an easy task. It certainly doesn't affect only Emacs. However, since this discussion _is_ in the context of Emacs, let me say this: FWIW, most changes I do in the Emacs docs do not justify using any of the commands discussed in this bug report and in the parallel thread on emacs-devel. I just make the changes by hand. I believe others do that as well. There are rare situations when I use the commands discussed here, typically close to a release when there's a need to make sure every menu is up to date. E.g., I didn't even remember the existence of texinfo-multiple-files-update until I bumped into a comment in emacs.texi, although I myself added that comment several years ago. I guess I'm saying that the importance of these commands in the context of maintaining Emacs documentation is somewhat exaggerated in this thread, to say the least ;-) ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 12:20 ` Eli Zaretskii @ 2011-12-08 14:46 ` Stefan Monnier 2011-12-10 11:00 ` Eli Zaretskii 2011-12-08 18:52 ` Roland Winkler 1 sibling, 1 reply; 24+ messages in thread From: Stefan Monnier @ 2011-12-08 14:46 UTC (permalink / raw) To: Eli Zaretskii; +Cc: winkler, Štěpán Němec, 2975, Karl Berry Karl writes: > Perhaps the description of texinfo-mode would be better off in the Emacs > manual, instead of the Texinfo manual. (Since it is not maintained as > part of Texinfo.) I'd be fine with that. Whatever you want to do. Sounds like a good idea, yes. Eli writes: > The simplest fix would be to remove the updating of the @node lines. > Would anyone object? Karl? That would be great. Eli writes: > I guess I'm saying that the importance of these commands in the > context of maintaining Emacs documentation is somewhat exaggerated in > this thread, to say the least ;-) IIUC the OP is not directly interested in maintaining Emacs documentation but rather is trying to write a manual for another project (BBDB, which happens to be an Emacs package). Eli writes: > Here's what I see there: > . texinfo-master-menu indeed does not support multiple-file manuals, > so it removed all the menu items whose nodes are in files other > than emacs.texi itself A good fix here would be for texinfo-master-menu to detect the problem and signal a warning/error. > . texinfo-master-menu doesn't grok @iftex and @ifnottext conditionals > (and probably the other @if... conditionals as well), so it > produced bad Next and Prev pointers, because, e.g., this: If leaving Node pointers alone fixes this problem, then there's nothing else to do, but otherwise texinfo-master-menu should try and detect these problematic cases and signal an error/warning. Stefan ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 14:46 ` Stefan Monnier @ 2011-12-10 11:00 ` Eli Zaretskii 0 siblings, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-10 11:00 UTC (permalink / raw) To: Stefan Monnier; +Cc: winkler, stepnem, 2975, karl > From: Stefan Monnier <monnier@IRO.UMontreal.CA> > Cc: Štěpán Němec <stepnem@gmail.com>, > 2975@debbugs.gnu.org, winkler@gnu.org, > Karl Berry > <karl@freefriends.org> > Date: Thu, 08 Dec 2011 09:46:49 -0500 > > Eli writes: > > The simplest fix would be to remove the updating of the @node lines. > > Would anyone object? Karl? > > That would be great. I made it extremely optional instead: only "C-u N" where N is a number would cause @node lines to be updated with next/prev/up pointers. > Eli writes: > > I guess I'm saying that the importance of these commands in the > > context of maintaining Emacs documentation is somewhat exaggerated in > > this thread, to say the least ;-) > > IIUC the OP is not directly interested in maintaining Emacs > documentation but rather is trying to write a manual for another project > (BBDB, which happens to be an Emacs package). He was asking about the effects of invoking these commands on emacs.texi. > Eli writes: > > Here's what I see there: > > . texinfo-master-menu indeed does not support multiple-file manuals, > > so it removed all the menu items whose nodes are in files other > > than emacs.texi itself > > A good fix here would be for texinfo-master-menu to detect the problem > and signal a warning/error. > > > . texinfo-master-menu doesn't grok @iftex and @ifnottext conditionals > > (and probably the other @if... conditionals as well), so it > > produced bad Next and Prev pointers, because, e.g., this: > > If leaving Node pointers alone fixes this problem, then there's nothing > else to do, but otherwise texinfo-master-menu should try and detect > these problematic cases and signal an error/warning. The detection and error signaling are left as an exercise for the interested readers ;-) ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 12:20 ` Eli Zaretskii 2011-12-08 14:46 ` Stefan Monnier @ 2011-12-08 18:52 ` Roland Winkler 2011-12-08 18:55 ` Roland Winkler ` (2 more replies) 1 sibling, 3 replies; 24+ messages in thread From: Roland Winkler @ 2011-12-08 18:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Štěpán Němec, 2975, Karl Berry On Thu Dec 8 2011 Eli Zaretskii wrote: > The simplest fix would be to remove the updating of the @node lines. > Would anyone object? Karl? A TeXnical question: what about using TeX to generate the output? To the best of my knowledge makinfo doesn't care about @node lines being up to date or not, it can fix them itself. Does the same hold for TeX? Roland ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 18:52 ` Roland Winkler @ 2011-12-08 18:55 ` Roland Winkler 2011-12-08 19:06 ` Štěpán Němec 2011-12-08 19:33 ` Eli Zaretskii 2 siblings, 0 replies; 24+ messages in thread From: Roland Winkler @ 2011-12-08 18:55 UTC (permalink / raw) To: Eli Zaretskii, `t^[pán N^[mec, 2975, Karl Berry On Thu Dec 8 2011 Roland Winkler wrote: > On Thu Dec 8 2011 Eli Zaretskii wrote: > > The simplest fix would be to remove the updating of the @node lines. > > Would anyone object? Karl? > > A TeXnical question: what about using TeX to generate the output? > To the best of my knowledge makinfo doesn't care about @node lines > being up to date or not, it can fix them itself. Does the same hold > for TeX? I am sorry, I overlooked you clarified this point in a previous post. Roland ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 18:52 ` Roland Winkler 2011-12-08 18:55 ` Roland Winkler @ 2011-12-08 19:06 ` Štěpán Němec 2011-12-08 19:37 ` Eli Zaretskii 2011-12-08 19:33 ` Eli Zaretskii 2 siblings, 1 reply; 24+ messages in thread From: Štěpán Němec @ 2011-12-08 19:06 UTC (permalink / raw) To: Roland Winkler; +Cc: 2975, Karl Berry On Thu, 08 Dec 2011 19:52:17 +0100 Roland Winkler wrote: > On Thu Dec 8 2011 Eli Zaretskii wrote: >> The simplest fix would be to remove the updating of the @node lines. >> Would anyone object? Karl? > > A TeXnical question: what about using TeX to generate the output? > To the best of my knowledge makinfo doesn't care about @node lines > being up to date or not, it can fix them itself. Does the same hold > for TeX? Unless I'm missing something, you already got an answer to this question in Eli's first reply in this thread: --- [Roland] > Of course, I believe that makeinfo can add the info about the node > pointers. But what about output formats not supported by makeinfo? > I believe that something like TeX needs them. [Eli] TeX doesn't need them. These pointers are there to allow traversing the on-line manual, and are not needed for non on-line versions. --- (Personally I found Eli's explanation confusing -- what does "on-line" mean here? If it means HTML, makeinfo does support HTML output -- does it mean it doesn't cope with missing node pointers in the HTML case? If it means the standard Info manuals, then that's the principal format supported, isn't it...) -- Štěpán ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 19:06 ` Štěpán Němec @ 2011-12-08 19:37 ` Eli Zaretskii 2011-12-08 19:59 ` Štěpán Němec 0 siblings, 1 reply; 24+ messages in thread From: Eli Zaretskii @ 2011-12-08 19:37 UTC (permalink / raw) To: Štěpán Němec; +Cc: 2975, winkler, karl > From: Štěpán Němec <stepnem@gmail.com> > Cc: Eli Zaretskii <eliz@gnu.org>, 2975@debbugs.gnu.org, Karl Berry <karl@freefriends.org> > Date: Thu, 08 Dec 2011 20:06:45 +0100 > > (Personally I found Eli's explanation confusing -- what does "on-line" > mean here? If it means HTML, makeinfo does support HTML output -- does > it mean it doesn't cope with missing node pointers in the HTML case? "On-line" means all on-line formats, including HTML. What do you mean by "it doesn't cope" -- who or what is "it" here? makeinfo does not need these pointers in the Texinfo sources to produce them in any of its outputs that are meant for on-line browsing. That includes HTML (and Info, of course). ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 19:37 ` Eli Zaretskii @ 2011-12-08 19:59 ` Štěpán Němec 2011-12-08 20:54 ` Roland Winkler 2011-12-09 7:30 ` Eli Zaretskii 0 siblings, 2 replies; 24+ messages in thread From: Štěpán Němec @ 2011-12-08 19:59 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 2975, Štěpán Němec, winkler, karl On Thu, Dec 08, 2011 at 09:37:29PM +0200, Eli Zaretskii wrote: > > From: Štěpán Němec <stepnem@gmail.com> > > Cc: Eli Zaretskii <eliz@gnu.org>, 2975@debbugs.gnu.org, Karl Berry > > <karl@freefriends.org> > > Date: Thu, 08 Dec 2011 20:06:45 +0100 > > > > (Personally I found Eli's explanation confusing -- what does > > "on-line" > > mean here? If it means HTML, makeinfo does support HTML output -- > > does > > it mean it doesn't cope with missing node pointers in the HTML case? > > "On-line" means all on-line formats, including HTML. > > What do you mean by "it doesn't cope" -- who or what is "it" here? makeinfo > makeinfo does not need these pointers in the Texinfo sources to > produce them in any of its outputs that are meant for on-line > browsing. That includes HTML (and Info, of course). Thank you for the clarification. Wouldn't it be even clearer (and simpler) to say that makeinfo just never needs those pointers? You wrote: TeX doesn't need them. These pointers are there to allow traversing the on-line manual, and are not needed for non on-line versions. So, given that makeinfo can add the info itself when needed, is there really ever any need for listing the node pointers explicitly at all? -- Štěpán ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 19:59 ` Štěpán Němec @ 2011-12-08 20:54 ` Roland Winkler 2011-12-09 7:28 ` Eli Zaretskii 2011-12-10 0:17 ` Karl Berry 2011-12-09 7:30 ` Eli Zaretskii 1 sibling, 2 replies; 24+ messages in thread From: Roland Winkler @ 2011-12-08 20:54 UTC (permalink / raw) To: Stepan Nemec; +Cc: 2975, karl On Thu Dec 8 2011 Št pán N mec wrote: > So, given that makeinfo can add the info itself when needed, is there > really ever any need for listing the node pointers explicitly at all? If Karl or whoever could answer this question with a clear "no, these node pointers are never needed" (say, for recent versions of makeinfo and other tools for formatting info pages) this could make things much easier! Roland ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 20:54 ` Roland Winkler @ 2011-12-09 7:28 ` Eli Zaretskii 2011-12-09 7:48 ` Roland Winkler 2011-12-10 0:17 ` Karl Berry 1 sibling, 1 reply; 24+ messages in thread From: Eli Zaretskii @ 2011-12-09 7:28 UTC (permalink / raw) To: Roland Winkler; +Cc: stepnem, 2975, karl > Date: Thu, 8 Dec 2011 14:54:55 -0600 > From: "Roland Winkler" <winkler@gnu.org> > Cc: Eli Zaretskii <eliz@gnu.org>, 2975@debbugs.gnu.org, karl@freefriends.org > > On Thu Dec 8 2011 Št pán N mec wrote: > > So, given that makeinfo can add the info itself when needed, is there > > really ever any need for listing the node pointers explicitly at all? > > If Karl or whoever could answer this question with a clear "no, these > node pointers are never needed" (say, for recent versions of makeinfo > and other tools for formatting info pages) this could make things > much easier! I tried to explain that already, in my original mail: they are not needed if you structure your Texinfo source according to the rules described in "(texinfo)makeinfo Pointer Creation". Most manuals should have no problems being structured like that (the Emacs User Manual and Emacs Lisp Manual are actually structured according to those rules), but some specialized uses of Texinfo cannot be limited to tree-like structure, or don't want to use sectioning commands (@chapter, @section, etc.) or menus, or want to order the nodes in some special way that defeats the automatic generation of node pointers. For these, you must explicitly have the Next, Prev, Up pointers in Texinfo. ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-09 7:28 ` Eli Zaretskii @ 2011-12-09 7:48 ` Roland Winkler 0 siblings, 0 replies; 24+ messages in thread From: Roland Winkler @ 2011-12-09 7:48 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stepnem, 2975, karl On Fri Dec 9 2011 Eli Zaretskii wrote: > I tried to explain that already, in my original mail: they are not > needed if you structure your Texinfo source according to the rules > described in "(texinfo)makeinfo Pointer Creation". > > Most manuals should have no problems being structured like that (the > Emacs User Manual and Emacs Lisp Manual are actually structured > according to those rules), but some specialized uses of Texinfo cannot > be limited to tree-like structure, or don't want to use sectioning > commands (@chapter, @section, etc.) or menus, or want to order the > nodes in some special way that defeats the automatic generation of > node pointers. For these, you must explicitly have the Next, Prev, Up > pointers in Texinfo. OK, thanks a lot. For me, this is an important clarification. Roland ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 20:54 ` Roland Winkler 2011-12-09 7:28 ` Eli Zaretskii @ 2011-12-10 0:17 ` Karl Berry 2011-12-10 10:57 ` Eli Zaretskii 1 sibling, 1 reply; 24+ messages in thread From: Karl Berry @ 2011-12-10 0:17 UTC (permalink / raw) To: winkler; +Cc: stepnem, 2975 > So, given that makeinfo can add the info itself when needed, is there > really ever any need for listing the node pointers explicitly at all? If Karl or whoever could answer this question with a clear "no, these node pointers are never needed" I believe Eli answered this, but to reiterate, it is only (very) exceptional manuals which might need node pointers. So if you're asking if texinfo-mode needs to keep supporting them, I would say, definitely not. In fact, I think it would be a good thing if it didn't. I have seen many authors have unnecessary problems due to texinfo-mode inserting the node pointers. k ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-10 0:17 ` Karl Berry @ 2011-12-10 10:57 ` Eli Zaretskii 0 siblings, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-10 10:57 UTC (permalink / raw) To: Karl Berry; +Cc: stepnem, winkler, 2975 > Date: Fri, 9 Dec 2011 16:17:41 -0800 > From: karl@freefriends.org (Karl Berry) > Cc: stepnem@gmail.com, eliz@gnu.org, 2975@debbugs.gnu.org > > > So, given that makeinfo can add the info itself when needed, is there > > really ever any need for listing the node pointers explicitly at all? > > If Karl or whoever could answer this question with a clear "no, these > node pointers are never needed" > > I believe Eli answered this, but to reiterate, it is only (very) > exceptional manuals which might need node pointers. > > So if you're asking if texinfo-mode needs to keep supporting them, I > would say, definitely not. In fact, I think it would be a good thing if > it didn't. I have seen many authors have unnecessary problems due to > texinfo-mode inserting the node pointers. I updated the commentary and the doc strings of the relevant functions in texnfo-upd.el to the effect that texinfo-update-node and the commands that call it should only be used if one knows what they are doing. I also made texinfo-master-menu call texinfo-update-node only if the prefix arg is numeric, because invoking texinfo-master-menu with just C-u is still useful and much less problematic. I decided not to remove the code that updates the @node lines entirely, since texinfo-update-node could still be useful to experts in very specialized use cases. I also added to the doc strings of relevant commands a note about non-support of multi-file Texinfo manuals, and a reference to texinfo-multiple-files-update, which does. I hope this makes the situation quite a bit better. ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 19:59 ` Štěpán Němec 2011-12-08 20:54 ` Roland Winkler @ 2011-12-09 7:30 ` Eli Zaretskii 1 sibling, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-09 7:30 UTC (permalink / raw) To: Štěpán Němec; +Cc: 2975, winkler, karl > Date: Thu, 8 Dec 2011 20:59:57 +0100 > From: "Štěpán Němec" <stepnem@gmail.com> > Cc: Štěpán Němec <stepnem@gmail.com>, > winkler@gnu.org, 2975@debbugs.gnu.org, karl@freefriends.org > > > makeinfo does not need these pointers in the Texinfo sources to > > produce them in any of its outputs that are meant for on-line > > browsing. That includes HTML (and Info, of course). > > Thank you for the clarification. Wouldn't it be even clearer (and > simpler) to say that makeinfo just never needs those pointers? It would, if it were true. But it isn't, see my other mail. ^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#2975: texinfo-master-menu and emacs.texi 2011-12-08 18:52 ` Roland Winkler 2011-12-08 18:55 ` Roland Winkler 2011-12-08 19:06 ` Štěpán Němec @ 2011-12-08 19:33 ` Eli Zaretskii 2 siblings, 0 replies; 24+ messages in thread From: Eli Zaretskii @ 2011-12-08 19:33 UTC (permalink / raw) To: Roland Winkler; +Cc: stepnem, 2975, karl > Date: Thu, 8 Dec 2011 12:52:17 -0600 > From: "Roland Winkler" <winkler@gnu.org> > Cc: Štěpán Němec <stepnem@gmail.com>, > 2975@debbugs.gnu.org, karl@freefriends.org (Karl Berry) > > On Thu Dec 8 2011 Eli Zaretskii wrote: > > The simplest fix would be to remove the updating of the @node lines. > > Would anyone object? Karl? > > A TeXnical question: what about using TeX to generate the output? > To the best of my knowledge makinfo doesn't care about @node lines > being up to date or not, it can fix them itself. Does the same hold > for TeX? TeX ignores @node. ^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2011-12-12 13:02 UTC | newest] Thread overview: 24+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-04-12 21:33 bug#2975: `texinfo-master-menu' doesn't work Alan Mackenzie 2011-12-10 12:40 ` Eli Zaretskii [not found] ` <837h24mwfs.fsf@gnu.org> [not found] ` <20111211173859.GA2755@acm.acm> 2011-12-11 18:18 ` Eli Zaretskii 2011-12-12 12:25 ` Alan Mackenzie 2011-12-12 13:02 ` Eli Zaretskii [not found] <20191.12232.556454.551166@gargle.gargle.HOWL> [not found] ` <E1RYHPD-0000vm-PC@fencepost.gnu.org> [not found] ` <h87h28tgcg.fsf@fencepost.gnu.org> [not found] ` <20191.48632.665251.448872@gargle.gargle.HOWL> 2011-12-07 20:43 ` bug#2975: texinfo-master-menu and emacs.texi Stefan Monnier 2011-12-07 21:19 ` Roland Winkler 2011-12-08 6:17 ` Eli Zaretskii 2011-12-08 10:38 ` Štěpán Němec 2011-12-08 12:20 ` Eli Zaretskii 2011-12-08 14:46 ` Stefan Monnier 2011-12-10 11:00 ` Eli Zaretskii 2011-12-08 18:52 ` Roland Winkler 2011-12-08 18:55 ` Roland Winkler 2011-12-08 19:06 ` Štěpán Němec 2011-12-08 19:37 ` Eli Zaretskii 2011-12-08 19:59 ` Štěpán Němec 2011-12-08 20:54 ` Roland Winkler 2011-12-09 7:28 ` Eli Zaretskii 2011-12-09 7:48 ` Roland Winkler 2011-12-10 0:17 ` Karl Berry 2011-12-10 10:57 ` Eli Zaretskii 2011-12-09 7:30 ` Eli Zaretskii 2011-12-08 19:33 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).