[6446] reorganize chapter on menus

[Gavin D. Smith]

Revision: 6446
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6446
Author:   gavin
Date:     2015-07-22 10:43:34 +0000 (Wed, 22 Jul 2015)
Log Message:
-----------
reorganize chapter on menus

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-07-21 19:14:43 UTC (rev 6445)
+++ trunk/ChangeLog     2015-07-22 10:43:34 UTC (rev 6446)
@@ -1,3 +1,21 @@
+2015-07-22  Gavin Smith  <address@hidden>
+
+       * doc/texinfo.texi (Writing A Menu): Move node before "Menu 
+       Location" node.
+       (Menus, Menu Location): Move advice on writing short nodes to 
+       Menu Location.
+       (Menu Parts, Menu Location): Move advice on how to access menu 
+       entries in Info to be next to the advice on how to access menu 
+       entries in HTML.
+       (Menu Location): Place obsolete advice within an @ignore block. 
+       Move exhortation to use a hierarchical structure to Writing A 
+       Menu, because that isn't to do with the menu location.
+       (Menu Example): Move node to be just after Writing A Menu node.
+       (Writing a Menu): Split paragraph about menu entries and menu 
+       comments into two.
+       (Writing a Menu, Menu Parts): Move advice about extraneous 
+       whitespace from Writing a Menu.
+
 2015-07-21  Gavin Smith  <address@hidden>
 
        * doc/texinfo.texi: Add \global\usebracesinindexestrue at start 

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-07-21 19:14:43 UTC (rev 6445)
+++ trunk/doc/texinfo.texi      2015-07-22 10:43:34 UTC (rev 6446)
@@ -153,13 +153,14 @@
 * Conditionals::                Specifying text for only some output cases.
 * Defining New Texinfo Commands:: User-defined macros and aliases.
 * Include Files::               How to incorporate other Texinfo files.
-
 * Hardcopy::                    Output for paper, with @TeX{}.
 * Generic Translator @command{texi2any}:: @command{texi2any}, an all-purpose 
converter.
 * Creating and Installing Info Files:: Details on Info output.
 * Generating HTML::             Details on HTML output.
 @c * texi2any Output Customization:: Fine tuning with initialization files.
 
+Appendices
+
 * Command List::                All the Texinfo @@-commands.
 * Tips::                        Hints on how to write a Texinfo document.
 * Sample Texinfo Files::        Complete examples, including full texts.
@@ -5606,38 +5607,49 @@
 you use menus to go to such nodes.  Menus have no effect in printed
 manuals and do not appear in them.
 
-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
+* Writing a Menu::              What is a menu?
+* Menu Example::                Two and three part menu entries.
 * 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.
-* Menu Example::                Two and three part menu entries.
 * Other Info Files::            How to refer to a different Info file.
 @end menu
 
 
address@hidden Menu Location
address@hidden Menu Location
address@hidden Menu location
address@hidden Location of menus
address@hidden Writing a Menu
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
 
-There may be at most one menu in a node.  A menu is conventionally
-located at the end of a node, without any regular text or additional
-commands between the @code{@@end menu} and the beginning of the next
-node.
+A menu consists of a @code{@@menu} command on a line by itself,
+followed by menu entry lines or menu comment lines, and then followed
+by an @code{@@end menu} command on a line by itself.
 
address@hidden Info format, and menus
-This convention is useful, since a reader who uses the menu could
-easily miss any such text.  Also, any such post-menu text will be
-considered part of the menu in Info output (which has no marker for
-the end of a menu).  Thus, a line beginning with @samp{* } will likely
-be incorrectly handled.
+A menu looks like this:
 
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files::                       All about handling files.
+* Multiples: Buffers.           Multiple buffers; editing
+                                 several files at once.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden Spaces, in menus
+In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
+entry}.  (Note the space after the asterisk.)
+
+A line that does not start with an @address@hidden }} may also appear in a
+menu.  Such a line is not a menu entry but rather a @dfn{menu comment}
+line that appears in the Info file.  In the example above, the line
address@hidden Units of Text} is such a menu comment line; the two lines
+starting with @address@hidden }} are menu entries.
+
 @cindex Hierarchical documents, and menus
 Technically, menus can carry you to any node, regardless of the
 structure of the document; even to nodes in a different Info file.
@@ -5648,29 +5660,52 @@
 subordinate nodes in a hierarchically structured document.  It is much
 better to use cross references to refer to arbitrary nodes.
 
-Years ago, we recommended using a @samp{@@heading} command within an
address@hidden@@ifinfo} conditional instead of the normal sectioning commands
-after a very short node with a menu.  This had the advantage of making
-the printed output look better, because there was no very short text
-between two headings on the page.  But it does not work with
address@hidden's implicit pointer creation, and it also makes the
-XML output incorrect, since it does not reflect the true document
-structure.  So, we no longer recommend this.
+In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
+command.  The menu entry name is what the user types after the @kbd{m}
+command.
address@hidden address@hidden, in HTML output of menus}
+In the HTML output from @command{makeinfo}, the @code{accesskey}
+attribute is used with the values @address@hidden@samp{9} for the
+first nine entries.  This allows people using web browsers to follow
+the first menu entries using (typically) @address@hidden, e.g.,
address@hidden for the first entry.
 
address@hidden Menu Example
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
 
address@hidden Writing a Menu
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
address@hidden merge with Writing a Menu node?
 
-A menu consists of a @code{@@menu} command on a line by itself
-followed by menu entry lines or menu comment lines and then by an
address@hidden@@end menu} command on a line by itself.
+A menu looks like this in Texinfo:
 
-A menu looks like this:
address@hidden
address@hidden
+@@menu
+* menu entry name: Node name.   A short description.
+* Node name::                   This form is preferred.
+@@end menu
address@hidden group
address@hidden example
 
address@hidden 800
address@hidden
+This produces:
+
 @example
 @group
+* menu:
+
+* menu entry name: Node name.   A short description.
+* Node name::                   This form is preferred.
address@hidden group
address@hidden example
+
address@hidden 700
+Here is an example as you might see it in a Texinfo file:
+
address@hidden
address@hidden
 @@menu
 Larger Units of Text
 
@@ -5681,27 +5716,66 @@
 @end group
 @end example
 
address@hidden Spaces, in menus
-In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
-entry}.  (Note the space after the asterisk.)  A line that does not
-start with an @address@hidden }} may also appear in a menu.  Such a line is
-not a menu entry but rather a @dfn{menu comment} line that appears in
-the Info file.  In the example above, the line @samp{Larger Units of
-Text} is such a menu comment line; the two lines starting with
address@hidden@samp{* }} are menu entries.  Space characters in a menu are
-preserved as-is in the Info output; this allows you to format the menu
-as you wish.  Unfortunately you must type node names without any extra
-spaces or some versions of some Info readers will not find the
-node (@pxref{Node Line Requirements}).
address@hidden 800
address@hidden
+This produces:
 
address@hidden address@hidden, in HTML output of menus}
-In the HTML output from @command{makeinfo}, the @code{accesskey}
-attribute is used with the values @address@hidden@samp{9} for the
-first nine entries.  This allows people using web browsers to follow
-the first menu entries using (typically) @address@hidden, e.g.,
address@hidden for the first entry.
address@hidden
address@hidden
+* menu:
+Larger Units of Text
 
+* Files::                       All about handling files.
+* Multiples: Buffers.           Multiple buffers; editing
+                                 several files at once.
address@hidden group
address@hidden example
 
+In this example, the menu has two entries.  @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an entry.
+
+Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files}).
+
+
address@hidden Menu Location
address@hidden Menu Location
address@hidden Menu location
address@hidden Location of menus
+
+There may be at most one menu in a node.  A menu is conventionally
+located at the end of a node, without any regular text or additional
+commands between the @code{@@end menu} and the beginning of the next
+node.
+
address@hidden Info format, and menus
+This convention is useful, since a reader who uses the menu could
+easily miss any such text.  Also, any such post-menu text will be
+considered part of the menu in Info output (which has no marker for
+the end of a menu).  Thus, a line beginning with @samp{* } will likely
+be incorrectly handled.
+
+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.
+
address@hidden
+Years ago, we recommended using a @samp{@@heading} command within an
address@hidden@@ifinfo} conditional instead of the normal sectioning commands
+after a very short node with a menu.  This had the advantage of making
+the printed output look better, because there was no very short text
+between two headings on the page.  But it does not work with
address@hidden's implicit pointer creation, and it also makes the
+XML output incorrect, since it does not reflect the true document
+structure.  So, we no longer recommend this.
address@hidden ignore
+
+
 @node Menu Parts
 @section The Parts of a Menu
 @cindex Parts of a menu
@@ -5728,21 +5802,10 @@
 * @var{menu-entry-name}: @var{node-name}.   @var{description}
 @end example
 
-Follow the menu entry name with a single colon and follow the node
+Follow the menu entry name with a single colon, and follow the node
 name with tab, comma, newline, or the two characters period and space
 (@samp{. }).
 
address@hidden warns when the text of a menu item (and node names
-and cross references) contains a problematic construct that will
-interfere with its parsing in Info.  If you don't want to see the
-warnings, you can set the customization variable
address@hidden to @samp{0} (@pxref{Other
-Customization Variables}).
-
-In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
-command.  The menu entry name is what the user types after the @kbd{m}
-command.
-
 The third part of a menu entry is a descriptive phrase or sentence.
 Menu entry names and node names are often short; the description
 explains to the reader what the node is about.  A useful description
@@ -5752,7 +5815,21 @@
 it with the first (and all others).  It's up to you.  An empty line,
 or the next menu entry, ends a description.
 
+Space characters in a menu are preserved as-is in the Info output; this
+allows you to format the menu as you wish.  Unfortunately you must type
+node names without any extra spaces or some versions of some Info
+readers will not find the node (@pxref{Node Line Requirements}).
 
+
address@hidden warns when the text of a menu item (and node names
+and cross references) contains a problematic construct that will
+interfere with its parsing in Info.  If you don't want to see the
+warnings, you can set the customization variable
address@hidden to @samp{0} (@pxref{Other
+Customization Variables}).
+
+
+
 @node Less Cluttered Menu Entry
 @section Less Cluttered Menu Entry
 @cindex Two part menu entry
@@ -5784,75 +5861,6 @@
 possible, since it reduces visual clutter in the menu.
 
 
address@hidden Menu Example
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
-
-A menu looks like this in Texinfo:
-
address@hidden
address@hidden
-@@menu
-* menu entry name: Node name.   A short description.
-* Node name::                   This form is preferred.
-@@end menu
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-This produces:
-
address@hidden
address@hidden
-* menu:
-
-* menu entry name: Node name.   A short description.
-* Node name::                   This form is preferred.
address@hidden group
address@hidden example
-
address@hidden 700
-Here is an example as you might see it in a Texinfo file:
-
address@hidden
address@hidden
-@@menu
-Larger Units of Text
-
-* Files::                       All about handling files.
-* Multiples: Buffers.           Multiple buffers; editing
-                                 several files at once.
-@@end menu
address@hidden group
address@hidden example
-
address@hidden 800
address@hidden
-This produces:
-
address@hidden
address@hidden
-* menu:
-Larger Units of Text
-
-* Files::                       All about handling files.
-* Multiples: Buffers.           Multiple buffers; editing
-                                 several files at once.
address@hidden group
address@hidden example
-
-In this example, the menu has two entries.  @samp{Files} is both a menu
-entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
-appears in the menu, but is not an entry.
-
-Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
-(@pxref{Other Info Files, , Referring to Other Info Files}).
-
 @node Other Info Files
 @section Referring to Other Info Files
 @cindex Referring to other Info files