From: Robert J. Chassell <bob@rattlesnake.com>
Date: Wed, 20 Feb 2002 17:39:38 +0000 (+0000)
Subject: (texinfo-insert-menu): Explain in doc string that
X-Git-Tag: ttn-vms-21-2-B4~16561
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=70e2c6a475a0af146e269224b25362f1895e8983;p=emacs.git

(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 --git a/lisp/textmodes/texnfo-upd.el b/lisp/textmodes/texnfo-upd.el
index eee804cd513..18ebb12e832 100644
--- a/lisp/textmodes/texnfo-upd.el
+++ b/lisp/textmodes/texnfo-upd.el
@@ -261,8 +261,12 @@ for nodes within or part of the marked region.
 
 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 @@ at the level specified by LEVEL.  Point is left at the end of menu."
 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 @@ node within the section."
 
 (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 @@ recommendation in the Texinfo Manual:
      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))