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

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  <eliz@gnu.org>
+
+        * 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  <mgrojo@gmail.com>  (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: