# HG changeset patch
# User Robert J. Chassell <bob@rattlesnake.com>
# Date 1014226778 0
# Node ID 5288b3225c40f6f15ac882b1b8a3fac0ad0c5da5
# Parent  e578c09a048570e8b1ccc44d9d17f7eb7ef64999
(texinfo-insert-menu): Explain in doc string that
descriptions are indented, and that menus without
descriptions will contain trailing whitespace instead;
argue for importance of descriptions.

(texinfo-all-menus-update, texinfo-master-menu,texinfo-make-menu)
Also, note reason for indentation in doc string.

diff -r e578c09a0485 -r 5288b3225c40 lisp/textmodes/texnfo-upd.el
--- a/lisp/textmodes/texnfo-upd.el	Wed Feb 20 14:52:54 2002 +0000
+++ b/lisp/textmodes/texnfo-upd.el	Wed Feb 20 17:39:38 2002 +0000
@@ -261,8 +261,12 @@
 
 Whenever a menu exists, and is being updated, the descriptions that
 are associated with node names in the pre-existing menu are
-incorporated into the new menu.  Otherwise, the nodes' section titles
-are inserted as descriptions."
+incorporated into the new menu.
+
+Leaves trailing whitespace in a menu that lacks descriptions, so
+descriptions will format well.  In general, a menu should contain
+descriptions, because node names and section titles are often too
+short to explain a node well."
 
   (interactive
    (if prefix-arg
@@ -329,7 +333,12 @@
 Update pre-existing master menu, if there is one.
 
 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.
+
+Indents the first line of descriptions, and leaves trailing whitespace
+in a menu that lacks descriptions, so descriptions will format well.
+In general, a menu should contain descriptions, because node names and
+section titles are often too short to explain a node well."
   (interactive "P")
   (let ((case-fold-search t)
 	master-menu-p)
@@ -651,8 +660,11 @@
 
 (defun texinfo-insert-menu (menu-list node-name)
   "Insert formatted menu at point.
-Indents the first line of the description, if any, to the value of
-texinfo-column-for-description.
+Indents the first line of descriptions, if any, to the value of
+texinfo-column-for-description.  Indenting leaves trailing whitespace
+in a menu that lacks descriptions, so descriptions will format well.
+In general, a menu should contain descriptions, because node names and
+section titles are often too short to explain a node well.
 
 MENU-LIST has form:
 
@@ -866,7 +878,12 @@
      specific information.
 
 Each of the menus in the detailed node listing is introduced by the
-title of the section containing the menu."
+title of the section containing the menu.
+
+Indents the first line of descriptions, and leaves trailing whitespace
+in a menu that lacks descriptions, so descriptions will format well.
+In general, a menu should contain descriptions, because node names and
+section titles are often too short to explain a node well."
 
   (interactive "P")
   (let ((case-fold-search t))