branch master updated: * doc/texinfo.texi (@itemize): Do not say that the argument has to "result in a single character in the Info file", as multiple characters do work fine as an argument. Remove description of what @bullet outputs in different output formats, for brevity. Move discussion of optional braces after the example. Move discussion of having at least one @item, index entries and comments, and blank lines after the example usage.

[Gavin D. Smith]

This is an automated email from the git hooks/post-receive script.

gavin pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 0ecf931bbe * doc/texinfo.texi (@itemize): Do not say that the argument 
has to "result in a single character in the Info file", as multiple characters 
do work fine as an argument. Remove description of what @bullet outputs in 
different output formats, for brevity.  Move discussion of optional braces 
after the example.  Move discussion of having at least one @item, index entries 
and comments, and blank lines after the example usage.
0ecf931bbe is described below

commit 0ecf931bbe69fa9c24276acaaf2a5fddb286e283
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Tue Mar 12 18:39:52 2024 +0000

    * doc/texinfo.texi (@itemize):
    Do not say that the argument has to "result in a single character
    in the Info file", as multiple characters do work fine as an argument.
    Remove description of what @bullet outputs in different output
    formats, for brevity.  Move discussion of optional braces after
    the example.  Move discussion of having at least one @item, index
    entries and comments, and blank lines after the example usage.
---
 ChangeLog        | 10 ++++++++++
 doc/texinfo.texi | 58 ++++++++++++++++++++++++++++----------------------------
 2 files changed, 39 insertions(+), 29 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d50281536c..ea6669a5db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2024-03-12  Gavin Smith <gavinsmith0123@gmail.com>
+
+       * doc/texinfo.texi (@itemize):
+       Do not say that the argument has to "result in a single character
+       in the Info file", as multiple characters do work fine as an argument.
+       Remove description of what @bullet outputs in different output
+       formats, for brevity.  Move discussion of optional braces after
+       the example.  Move discussion of having at least one @item, index
+       entries and comments, and blank lines after the example usage.
+
 2024-03-12  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/XS/convert/get_html_perl_info.c
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 8134324275..e8df8ccb13 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -6742,42 +6742,19 @@ 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
-a line.  Follow the command, on the same line, with a character or a
-Texinfo command that generates a mark.  Usually, you will use
-@code{@@bullet} after @code{@@itemize}, but you can use
-@code{@@minus}, or any command or character that results in a single
-character in the Info file.  (When you write the mark command such as
-@code{@@bullet} after an @code{@@itemize} command, you may omit the
-@samp{@{@}}.)  If you don't specify a mark command, the default is
-@code{@@bullet}.  If you don't want any mark at all, but still want
-logical items, use @code{@@w@{@}} (in this case the braces are
-required).
+a line.  Follow the command, on the same line, with a Texinfo command
+or character to generate a mark.  Usually, you will use @code{@@bullet}
+after @code{@@itemize}, but you can use @code{@@minus}, or any other
+Texinfo command or character.  If you don't specify a mark command,
+the default is @code{@@bullet}.
 
 @findex item @r{in @code{@@itemize}}
 After the @code{@@itemize}, write your items, each starting with
 @code{@@item}.  Text can follow on the same line as the @code{@@item}.
 The text of an item can continue for more than one paragraph.
 
-There should be at least one @code{@@item} inside the @code{@@itemize}
-environment.  If none are present, @code{texi2any} gives a warning.
-If you just want indented text and not a list of items, use
-@code{@@indentedblock}; @pxref{@code{@@indentedblock}}.
-
-Index entries and comments that are given before an @code{@@item}
-including the first, are automatically moved (internally) to after the
-@code{@@item}, so the output is as expected.  Historically this has
-been a common practice.
-
-Usually, you should put a blank line between items.  This puts a blank
-line in the Info file. (@TeX{} inserts the proper 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
-a round dot in other output formats.
+Here is an example of the use of @code{@@itemize}:
 
 @example
 @group
@@ -6806,6 +6783,29 @@ for bar.
 @end itemize
 @end quotation
 
+As you can see from this example, when you give a mark command such as
+@code{@@bullet} as the argument to @code{@@itemize} command, you may
+omit the @samp{@{@}} that would normally follow the command.
+
+@cindex @code{@@w}, for blank items
+If you don't want any mark at all, but still want logical items, use
+@code{@@w@{@}} (in this case the braces are required).
+
+There should be at least one @code{@@item} inside the @code{@@itemize}
+environment.  If none are present, @code{texi2any} gives a warning.
+If you just want indented text and not a list of items, use
+@code{@@indentedblock}; @pxref{@code{@@indentedblock}}.
+
+Index entries and comments that are given before an @code{@@item}
+including the first, are automatically moved (internally) to after the
+@code{@@item}, so the output is as expected.  Historically this has
+been a common practice.
+
+Usually, you should put a blank line between items.  This puts a blank
+line in the Info file. (@TeX{} inserts the proper vertical space in
+any case.)  Except when the entries are very brief, these blank lines
+make the list look better.
+
 Itemized lists may be embedded within other itemized lists.  Here is a
 list marked with dashes embedded in a list marked with bullets: