texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/06/19 23:16:43

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Menus): updates to this chapter

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1375&r2=1.1376
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.447&r2=1.448

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1375
retrieving revision 1.1376
diff -u -b -r1.1375 -r1.1376
--- ChangeLog   15 Jun 2012 18:34:19 -0000      1.1375
+++ ChangeLog   19 Jun 2012 23:16:42 -0000      1.1376
@@ -1,7 +1,13 @@
+2012-06-19  Patrice Dumas  <address@hidden>
+        and Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Menus): general updates throughout
+       the chapter.
+
 2012-06-15  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi: remove all now-unnecessary @refill's
-       and @ignore blocks relating to the long-gone @ctrl and @br,
+       and @ignore blocks relating to the long-gone @ctrl, @br, etc.,
        for source clarity.
 
 2012-06-14  Patrice Dumas  <address@hidden>

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.447
retrieving revision 1.448
diff -u -b -r1.447 -r1.448
--- doc/texinfo.txi     15 Jun 2012 18:34:19 -0000      1.447
+++ doc/texinfo.txi     19 Jun 2012 23:16:42 -0000      1.448
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.447 2012/06/15 18:34:19 karl Exp $
address@hidden $Id: texinfo.txi,v 1.448 2012/06/19 23:16:42 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -5530,13 +5530,13 @@
 you use menus to go to such nodes.  Menus have no effect in printed
 manuals and do not appear in them.
 
-A node with a menu should not contain much text.  If you find yourself
-writing a lot of text before a menu, we generally recommend moving
-most of the text into a new subnode---all but a paragraph or two.
+It's usually best if a node with a menu does not contain much text.
+If you find yourself with a lot of text before a menu, we generally
+recommend moving all but a couple of paragraphs into a new subnode.
 Otherwise, it is easy for readers to miss the menu.
 
 @menu
-* Menu Location::               Menus go at the ends of short nodes.
+* Menu Location::               Menus go at the ends of nodes.
 * Writing a Menu::              What is a menu?
 * Menu Parts::                  A menu entry has three parts.
 * Less Cluttered Menu Entry::   Two part menu entry.
@@ -5579,7 +5579,7 @@
 short text between two headings on the page.  But this also does not
 work with @command{makeinfo}'s implicit pointer creation, and it also
 makes the XML output incorrect, since it does not reflect the true
-document structure.  So, regrettably, we can no longer recommend this.
+document structure.  So, we no longer recommend this.
 
 
 @node Writing a Menu
@@ -5661,9 +5661,10 @@
 Menu entry names and node names are often short; the description
 explains to the reader what the node is about.  A useful description
 complements the node name rather than repeats it.  The description,
-which is optional, can spread over two or more lines; if it does, some
-authors prefer to indent the second line while others prefer to align it
-with the first (and all others).  It's up to you.
+which is optional, can spread over multiple lines; if it does, some
+authors prefer to indent the second line while others prefer to align
+it with the first (and all others).  It's up to you.  An empty line,
+or the next menu entry, ends a description.
 
 
 @node Less Cluttered Menu Entry
@@ -5776,24 +5777,19 @@
 
 You can create a menu entry that enables a reader in Info to go to a
 node in another Info file by writing the file name in parentheses just
-before the node name.  In this case, you should use the three-part menu
-entry format, which saves the reader from having to type the file
-name.
-
address@hidden 800
-The format looks like this:
+before the node name.  Some examples:
 
 @example
 @group
 @@menu
 * @var{first-entry-name}:(@var{filename})@var{nodename}.     @var{description}
-* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
+* (@var{filename})@var{second-node}::                  @var{description}
 @@end menu
 @end group
 @end example
 
 For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you would write a
address@hidden nodes in the @cite{Emacs Manual}, you could write a
 menu like this:
 
 @example
@@ -5801,35 +5797,23 @@
 @@menu
 * Outlining: (emacs)Outline Mode. The major mode for
                                    editing outlines.
-* Rebinding: (emacs)Rebinding.    How to redefine the
+* (emacs)Rebinding::              How to redefine the
                                    meaning of a key.
 @@end menu
 @end group
 @end example
 
 If you do not list the node name, but only name the file, then Info
-presumes that you are referring to the `Top' node.
-
-The @file{dir} file that contains the main menu for Info has menu
-entries that list only file names.  These take you directly to the `Top'
-nodes of each Info document.  (@xref{Installing an Info File}.)
-
address@hidden 700
-For example:
+presumes that you are referring to the `Top' node.  Examples:
 
 @example
 @group
 * Info: (info).         Documentation browsing system.
-* Emacs: (emacs).       The extensible, self-documenting
+* (emacs)::             The extensible, self-documenting
                        text editor.
 @end group
 @end example
 
address@hidden
-(The @file{dir} top level directory for the Info system is an Info file,
-not a Texinfo file, but a menu entry looks the same in both types of
-file.)
-
 The GNU Emacs Texinfo mode menu updating commands only work with nodes
 within the current buffer, so you cannot use them to create menus that
 refer to other files.  You must write such menus by hand.
@@ -21993,7 +21977,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.447 2012/06/15 18:34:19 karl Exp $
+$Id: texinfo.txi,v 1.448 2012/06/19 23:16:42 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}