From e5d84bfe065f1d8172165ee2bdd15193f7447d8a Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 10 Dec 2011 12:49:33 +0200 Subject: [PATCH] Fix documentation and one misfeature of Texinfo mode update commands. lisp/textmodes/texnfo-upd.el: Update commentary. Add a warning not to use texinfo-update-node and commands that call it if the Texinfo file uses @node lines without next/prev/up pointers. (texinfo-all-menus-update, texinfo-master-menu) (texinfo-update-node, texinfo-every-node-update) (texinfo-multiple-files-update): Doc fix. Warn against updating all the @node lines. (texinfo-master-menu): Only call texinfo-update-node if the prefix argument is numeric. See also this thread: http://lists.gnu.org/archive/html/emacs-devel/2011-12/msg00156.html. Fixes: debbugs:2975 --- lisp/ChangeLog | 13 +++++ lisp/textmodes/texnfo-upd.el | 95 ++++++++++++++++++++++++++++-------- 2 files changed, 87 insertions(+), 21 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index ed5af2e2b20..3d1f85ea73e 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,16 @@ +2011-12-10 Eli Zaretskii + + * textmodes/texnfo-upd.el: Update commentary. Add a warning not + to use texinfo-update-node and commands that call it if the + Texinfo file uses @node lines without next/prev/up pointers. + (texinfo-all-menus-update, texinfo-master-menu) + (texinfo-update-node, texinfo-every-node-update) + (texinfo-multiple-files-update): Doc fix. Warn against updating + all the @node lines. + (texinfo-master-menu): Only call texinfo-update-node if the prefix + argument is numeric. (Bug#2975) See also this thread: + http://lists.gnu.org/archive/html/emacs-devel/2011-12/msg00156.html. + 2011-12-09 Manuel Gómez (tiny change) * speedbar.el (speedbar-supported-extension-expressions): diff --git a/lisp/textmodes/texnfo-upd.el b/lisp/textmodes/texnfo-upd.el index 047bba72ccd..e21e8ba7623 100644 --- a/lisp/textmodes/texnfo-upd.el +++ b/lisp/textmodes/texnfo-upd.el @@ -23,7 +23,9 @@ ;;; Commentary: -;; Known bug: update commands fail to ignore @ignore. +;; Known bug: update commands fail to ignore @ignore, and fail to DTRT +;; with the @if... directives (so expect trouble when the manual uses +;; different @node lines or @menu items in @iftex and in @ifnottex). ;; Summary: how to use the updating commands @@ -37,6 +39,16 @@ ;; With a prefix argument, the `texinfo-update-node' and ;; `texinfo-make-menu' functions do their jobs in the region. ;; +;; Important note: We do NOT recommend use of these commands to update +;; the `Next', `Previous' and `Up' pointers on @node lines. Most +;; manuals, including those whose Texinfo files adhere to the strucure +;; described below, don't need these pointers, because makeinfo will +;; generate them automatically (see the node "makeinfo Pointer +;; Creation" in the Texinfo manual). By contrast, due to known bugs +;; described above, texinfo-update-node etc. could produce incorrect +;; pointers, and thus make a perfectly valid Texinfo file into an +;; invalid one. You _have_ been warned! +;; ;; In brief, the functions for creating or updating nodes and menus, are: ;; ;; texinfo-update-node (&optional beginning end) @@ -89,6 +101,16 @@ ;; It does not matter whether the `@node' line has pre-existing ;; `Next', `Previous', or `Up' pointers in it. They are removed. +;; Warning: Since the pre-existing pointers are replaced with the ones +;; computed by `texinfo-update-node', and since this function has +;; known bugs with the more advanced Texinfo features (see above), it +;; could produce an invalid Texinfo file. You are well advised not to +;; use this function, except if you know what you are doing and +;; exercise extreme caution. Keep in mind that most manuals do not +;; need the `Next', `Previous', and `Up' pointers to be present on the +;; @node lines; makeinfo will automatically generate them when it +;; produces the Info or HTML versions of the manual. + ;; The `texinfo-every-node-update' function runs `texinfo-update-node' ;; on the whole buffer. @@ -119,12 +141,15 @@ ;; on the whole buffer. ;; The `texinfo-master-menu' function creates an extended menu located -;; after the top node. (The file must have a top node.) The function -;; first updates all the regular menus in the buffer (incorporating the -;; descriptions from pre-existing menus), and then constructs a master -;; menu that includes every entry from every other menu. (However, the -;; function cannot update an already existing master menu; if one -;; exists, it must be removed before calling the function.) +;; after the top node. (The file must have a top node.) This +;; function works only on Texinfo files all of whose @node lines are +;; present in a single file; use `texinfo-multiple-files-update' for +;; multi-file manuals. The function first updates all the regular +;; menus in the buffer (incorporating the descriptions from +;; pre-existing menus), and then constructs a master menu that +;; includes every entry from every other menu. (However, the function +;; cannot update an already existing master menu; if one exists, it +;; must be removed before calling the function.) ;; The `texinfo-indent-menu-description' function indents every ;; description in the menu following point, to the specified column. @@ -142,7 +167,7 @@ ;; as node names in pre-existing `@node' lines that lack names. ;; ;; Since node names should be more concise than section or chapter -;; titles, node names so inserted will need to be edited manually. +;; titles, you will usually want to manually edit node names so inserted. ;;; Code: @@ -330,8 +355,13 @@ at the level specified by LEVEL. Point is left at the end of menu." "Update every regular menu in a Texinfo file. Update pre-existing master menu, if there is one. +Only single-file manuals are supported by this function. For +multi-file manuals, use `texinfo-multiple-files-update'. + If called with a non-nil argument, this function first updates all the -nodes in the buffer before updating the menus. +nodes in the buffer before updating the menus. Do NOT invoke this +command with an argument if your Texinfo file uses @node lines without +the `Next', `Previous', and `Up' pointers! Indents the first line of descriptions, and leaves trailing whitespace in a menu that lacks descriptions, so descriptions will format well. @@ -843,17 +873,25 @@ second and subsequent lines of a multi-line description." (defun texinfo-master-menu (update-all-nodes-menus-p) "Make a master menu for a whole Texinfo file. -Non-nil argument (prefix, if interactive) means first update all -existing nodes and menus. Remove pre-existing master menu, if there is one. +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'. + +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! This function creates a master menu that follows the top node. The master menu includes every entry from all the other menus. It replaces any existing ordinary menu that follows the top node. -If called with a non-nil argument, this function first updates all the -menus in the buffer (incorporating descriptions from pre-existing -menus) before it constructs the master menu. - The function removes the detailed part of an already existing master menu. This action depends on the pre-existing master menu using the standard `texinfo-master-menu-header'. @@ -909,10 +947,11 @@ section titles are often too short to explain a node well." (if update-all-nodes-menus-p (progn - (message "Making a master menu in %s ...first updating all nodes... " - (buffer-name)) - (texinfo-update-node (point-min) (point-max)) - + (when (numberp update-all-nodes-menus-p) + (message + "Making a master menu in %s ...first updating all nodes... " + (buffer-name)) + (texinfo-update-node (point-min) (point-max))) (message "Updating all menus in %s ... " (buffer-name)) (texinfo-make-menu (point-min) (point-max)))) @@ -1207,6 +1246,11 @@ end of that region; it limits the search." "Without any prefix argument, update the node in which point is located. Interactively, a prefix argument means to operate on the region. +Warning: do NOT use this function if your Texinfo file uses @node +lines without the `Next', `Previous', `Up' pointers, because the +result could be an invalid Texinfo file due to known deficiencies +in this command: it does not support @ignore and @if* directives. + The functions for creating or updating nodes and menus, and their keybindings, are: @@ -1246,7 +1290,12 @@ which menu descriptions are indented. Its default value is 32." (message "Done...nodes updated in region. You may save the buffer.")))))) (defun texinfo-every-node-update () - "Update every node in a Texinfo file." + "Update every node in a Texinfo file. + +Warning: do NOT use this function if your Texinfo file uses @node +lines without the `Next', `Previous', `Up' pointers, because the +result could be an invalid Texinfo file due to known deficiencies +in this command: it does not support @ignore and @if* directives." (interactive) (save-excursion (texinfo-update-node (point-min) (point-max)) @@ -1934,7 +1983,11 @@ With optional UPDATE-EVERYTHING argument (numeric prefix arg, if interactive), update all the menus and all the `Next', `Previous', and `Up' pointers of all the files included in OUTER-FILE before inserting a master menu in OUTER-FILE. Also, update the `Top' level node -pointers of OUTER-FILE. +pointers of OUTER-FILE. Do NOT invoke this command with a numeric prefix +arg, if your files use @node lines without the `Next', `Previous', `Up' +pointers, because this could produce invalid Texinfo files due to known +deficiencies in `texinfo-update-node': it does not support the @ignore +and @if... directives. Notes: -- 2.39.2