Doc: CG 4.3.6 Syntax survey: Elaborate @itemize guidance

 - actually elaborate @enumerate, since @itemize simply
   refers to this

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index a42d029b15fc3a3dc253f2246eafdc508a3daf6b..0162670763dd2f895811de0bfab6675e17d96083 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -756,16 +756,33 @@ Don't capitalize the first word.
 @itemize
 @item
 @code{@@enumerate} --- Create an ordered list (with numbers).
-Always put @samp{@@item} on its own line, and separate consecutive
-items with a blank line:
+Always put @samp{@@item} on its own line.  As an exception, if all
+the items in the list are short enough to fit on single lines, placing
+them on the @samp{@@item} lines is also permissible.  @samp{@@item}
+and @samp{@@end@tie{}enumerate} should always be preceded by a blank
+line.
 
 @example
 @@enumerate
+
 @@item
-Foo
+A long multi-line item like this one must begin
+on a line of its own and all the other items in
+the list must do so too.
 
 @@item
-Bar
+Even short ones
+
+@@end enumerate
+@end example
+
+@example
+@@enumerate
+
+@@item Short item
+
+@@item Short item
+
 @@end enumerate
 @end example