[5193] clarify @itemize behavior (no text before first @item), and @ set allowed in the midst of a line

[karl]

Revision: 5193
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5193
Author:   karl
Date:     2013-02-23 00:56:16 +0000 (Sat, 23 Feb 2013)
Log Message:
-----------
clarify @itemize behavior (no text before first @item), and @set allowed in the 
midst of a line

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/NEWS
    trunk/README-hacking
    trunk/doc/texinfo.txi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2013-02-23 00:12:40 UTC (rev 5192)
+++ trunk/ChangeLog     2013-02-23 00:56:16 UTC (rev 5193)
@@ -1,3 +1,12 @@
+2013-02-22  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (@t{@@set @@value}): mention that @set
+       need not appear at the beginning of a line.
+       (@t{@@enumerate}, @t{@@itemize}): clarify that normal text cannot
+       appear before the first @item (any more).
+       
+       * README-hacking: include CPAN update in release procedure.
+
 2013-02-22  Antonio Diaz Diaz  <address@hidden>  (tiny change)
 
        * info/filesys.c (compress_suffixes): Add .lz/lzip.

Modified: trunk/NEWS
===================================================================
--- trunk/NEWS  2013-02-23 00:12:40 UTC (rev 5192)
+++ trunk/NEWS  2013-02-23 00:56:16 UTC (rev 5193)
@@ -23,6 +23,11 @@
 
 -------------------------------------------------------------------------------
 5.1
+* texi2any:
+  . irregular sectioning trees (see 5.0 news item) produce a warning
+    rather than an error.
+  . @set in the middle of the line no longer produces a warning.
+  
 * info:
   . lzip (.lz) compression supported.
   
@@ -84,9 +89,13 @@
   . The previous makeinfo implementation accepted text inside @itemize,
     @enumerate, etc., not within the scope of an @item.  This is
     semantically inconsistent, leading to problems with some backends,
-    and thusnow produces a warning.
+    and thus now produces a warning.
     
-  . The previous makeinfo accepted ``irregular'' sectioning trees, for
+  . The previous makeinfo accepted ``irregular'' sectioning trees.  Now
+    when @node pointers are implicitly determined, the consistency of
+    @menu and the sectioning tree is checked.  (If node pointers are
+    explicitly specified in the document, the tree can still be irregular.)
+
     example, when @top is not associated with the first node,
     subsections are written directly under chapters (skipping levels),
     and so on.  This produces an error in 5.0 and will be a warning in

Modified: trunk/README-hacking
===================================================================
--- trunk/README-hacking        2013-02-23 00:12:40 UTC (rev 5192)
+++ trunk/README-hacking        2013-02-23 00:56:16 UTC (rev 5193)
@@ -152,3 +152,5 @@
   ... announcements:
 news item at savannah.
 send announcement to info-gnu, cc bug-texinfo.
+
+  ... update on CPAN.

Modified: trunk/doc/texinfo.txi
===================================================================
--- trunk/doc/texinfo.txi       2013-02-23 00:12:40 UTC (rev 5192)
+++ trunk/doc/texinfo.txi       2013-02-23 00:56:16 UTC (rev 5193)
@@ -9016,9 +9016,9 @@
 @findex itemize
 @cindex Itemization
 
-The @code{@@itemize} command produces sequences of indented
-paragraphs, with a bullet or other mark inside the left margin
-at the beginning of each paragraph for which such a mark is desired.
+The @code{@@itemize} command produces a sequence of ``items'', each
+starting with a bullet or other mark inside the left margin, and
+generally indented.
 
 @cindex @code{@@w}, for blank items
 Begin an itemized list by writing @code{@@itemize} at the beginning of
@@ -9029,22 +9029,32 @@
 character in the Info file.  (When you write the mark command such as
 @code{@@bullet} after an @code{@@itemize} command, you may omit the
 @address@hidden@}}.)  If you don't specify a mark command, the default is
address@hidden@@bullet}.  If you don't want any mark at all, use
address@hidden@@address@hidden@}} (in this case the braces are required).
address@hidden@@bullet}.
 
-Write the text of the indented paragraphs themselves after the
address@hidden@@itemize}, up to another line that says @code{@@end
-itemize}.
+If you don't want any mark at all, but still want items, use
address@hidden@@address@hidden@}} (in this case the braces are required).  If 
you just
+want indented text and not a list of items, use
address@hidden@@indentedblock}; @address@hidden@@indentedblock}}.
 
 @findex item
-At the beginning of each paragraph for which a mark in the margin is
-desired, write a line that starts with @code{@@item}.  It is ok to
-have text following the @code{@@item}.
+After the @code{@@itemize}, write your items, each starting with
address@hidden@@item}.  Text can follow on the same line as the @code{@@item}.
+The text of an item can continue for more than one paragraph.
 
+On the other hand, normal text before the first @code{@@item}
+(``outside'' of any item) produces a warning, since some output
+formats (e.g., HTML, Docbook) strictly require all text inside an
+itemized list to be associated with an item.
+
+Index entries and comments are allowed before @code{@@item}, though,
+including the first, since historically this has been a common
+practice.  They automatically moved (internally) to after the
address@hidden@@item}, so the output is as expected.
+
 Usually, you should put a blank line before an @code{@@item}.  This
 puts a blank line in the Info file. (@TeX{} inserts the proper
-interline whitespace in either case.)  Except when the entries are
-very brief, these blank lines make the list look better.
+vertical space in any case.)  Except when the entries are very brief,
+these blank lines make the list look better.
 
 Here is an example of the use of @code{@@itemize}, followed by the
 output it produces.  @code{@@bullet} produces an @samp{*} in Info and
@@ -9129,9 +9139,9 @@
 @findex enumerate
 @cindex Enumeration
 
address@hidden@@enumerate} is like @code{@@itemize}
-(@address@hidden@@itemize}}), except that the labels on the items are
-successive integers or letters instead of bullets.
address@hidden@@enumerate} is like @code{@@itemize} 
(@address@hidden@@itemize}}),
+except that the labels on the items are successive integers or letters
+instead of bullets.
 
 Write the @code{@@enumerate} command at the beginning of a line.  The
 command does not require an argument, but accepts either a number or a
@@ -9143,8 +9153,9 @@
 
 Write the text of the enumerated list in the same way as an itemized
 list: write a line starting with @code{@@item} at the beginning of
-each paragraph that you want enumerated.  It is ok to have text
-following the @code{@@item}.
+each item in the enumeration.  It is ok to have text following the
address@hidden@@item}, and the text for an item can continue for several
+paragraphs.
 
 You should put a blank line between entries in the list.
 This generally makes it easier to read the Info file.
@@ -14224,6 +14235,8 @@
 limitations in @TeX{}.
 
 The value is the remainder of the input line, and can contain anything.
+However, unlike most other commands which take the rest of the line as
+a value, @code{@@set} need not appear at the beginning of a line.
 
 Write the @code{@@set} command like this: