[Emacs-diffs] /srv/bzr/emacs/trunk r106651: Fix bug #2975 with insufficient docs of texinfo-master-menu.

[Eli Zaretskii]

------------------------------------------------------------
revno: 106651
fixes bug(s): http://debbugs.gnu.org/2975
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2011-12-10 14:22:25 +0200
message:
  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.
modified:
  lisp/ChangeLog
  lisp/textmodes/texnfo-upd.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-12-10 10:49:33 +0000
+++ b/lisp/ChangeLog    2011-12-10 12:22:25 +0000
@@ -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  <address@hidden>  (tiny change)

=== modified file 'lisp/textmodes/texnfo-upd.el'
--- a/lisp/textmodes/texnfo-upd.el      2011-12-10 10:49:33 +0000
+++ b/lisp/textmodes/texnfo-upd.el      2011-12-10 12:22:25 +0000
@@ -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 @@
 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 @@
 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 @@
   (let ((first-chapter
         (save-excursion (re-search-forward "address@hidden|address@hidden") 
(point))))
     (unless (re-search-forward "address@hidden" 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)