Fix bug #2975 with insufficient docs of texinfo-master-menu.

 lisp/textmodes/texnfo-upd.el: Correct outdated description about
 texinfo-master-menu.
 (texinfo-master-menu): Explain better in the doc string what the
 function really does.
 (texinfo-insert-master-menu-list): Improve the error message
 displayed if there's no menu in the Top node.

2 files changed, 28 insertions, 16 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 3d1f85ea73e..74fc51c5e69 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -3,12 +3,17 @@
         * 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.
+        Correct outdated description about texinfo-master-menu.
         (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:
+        argument is numeric.  Explain better in the doc string what the
+        function really does.
+        (texinfo-insert-master-menu-list): Improve the error message
+        displayed if there's no menu in the Top node.
+        (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)
diff --git a/lisp/textmodes/texnfo-upd.el b/lisp/textmodes/texnfo-upd.el
index e21e8ba7623..d674b3a397e 100644
--- a/lisp/textmodes/texnfo-upd.el
+++ b/lisp/textmodes/texnfo-upd.el
@@ -142,14 +142,14 @@
 
 ;; The `texinfo-master-menu' function creates an extended menu located
 ;; after the top node.  (The file must have a top node.)  This
-;; function works only on Texinfo files all of whose @node lines are
+;; function works only on Texinfo files all of whose menus 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.)
+;; multi-file manuals.  The function constructs a master menu that
+;; includes every entry from every other menu.  Use this command to
+;; create or update the @detailmenu menu after you've created or
+;; updated all the menus in the file, including the menu in the Top
+;; node, using the `texinfo-make-menu' or the `texinfo-all-menus-update'
+;; command.
 
 ;; The `texinfo-indent-menu-description' function indents every
 ;; description in the menu following point, to the specified column.
@@ -878,6 +878,16 @@ 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
@@ -888,13 +898,10 @@ 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.
-
-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'.
+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:
@@ -1017,7 +1024,7 @@ However, there does not need to be a title field."
   (let ((first-chapter
          (save-excursion (re-search-forward "^@node\\|^@include") (point))))
     (unless (re-search-forward "^@menu" first-chapter t)
-      (error "Buffer lacks ordinary `Top' menu in which to insert master")))
+      (error "Buffer lacks a menu in its first node; create it, then run me again")))
   (beginning-of-line)
   (delete-region      ; buffer must have ordinary top menu
    (point)