On Tue, Mar 12, 2024 at 06:39:46PM +0000, Gavin Smith wrote:
> I think both should be documented as being valid. I don't mind which one
> is presented as more normal. I have edited the node in the documentation
> slightly.
>
> It would be ok to change the example to show "@itemize @bullet{}" instead
> of "@itemize @bullet" as long as the possibility of omitting the braces
> was still shown somewhere. This might potentially make the documentation
> easier to read, as the discussion of braces could be given less prominence.
Here is a proposal, with also removal of some text that imply that
braces always need to be omitted (and, in my opinion should be
removed idependentely of the other issue). Would that be ok to commit?
> I didn't really know what this part meant:
>
> 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.
>
> Methinks comments don't affect the output so moving them is irrelevant.
> I thought this could be rewritten to something like
>
> Index entries that occur immediately before an @code{@@item}
> are associated with the @code{@@item}.
Even though the information given on comments is relevant, I agree that
it is expected and does not need to be mentionned. I also agree with
avoiding to mention some implementation details.
There is also some text in @node Other Customization Variables
TREE_TRANSFORMATIONS description that provides a similar information
that you may consider changing:
@item move_index_entries_after_items
In @code{@@enumerate} and @code{@@itemize}, move index entries
appearing just before an @code{@@item} to just after the
@code{@@item}. Comment lines between index entries are moved too. As
mentioned, this is always done for HTML and DocBook output.
--
Pat
diff --git a/ChangeLog b/ChangeLog
index 4aa98d1e34..0d3ed03c7a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-03-14 Patrice Dumas <pertu...@free.fr>
+
+ * doc/texinfo.texi (Introducing Lists, @code{@@itemize}): use {} in
+ examples with mark commands @itemize arguments.
+
+ * doc/texinfo.texi (@code{@@bullet}, Click Sequences): remove text
+ stating that mark commands @itemize arguments braces are normally
+ omitted that are also of dubious interest.
+
2024-03-13 Patrice Dumas <pertu...@free.fr>
* tp/Texinfo/Convert/HTML.pm (_prepare_title_titlepage)
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index e8df8ccb13..13fcd4ee68 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -6685,7 +6685,7 @@ @node Introducing Lists
@noindent
Here is an itemized list of the different kinds of table and lists:
-@itemize @bullet
+@itemize @bullet{}
@item
Itemized lists with and without bullets.
@@ -6758,7 +6758,7 @@ @node @code{@@itemize}
@example
@group
-@@itemize @@bullet
+@@itemize @@bullet@{@}
@@item
Some text for foo.
@@ -6773,7 +6773,7 @@ @node @code{@@itemize}
This produces:
@quotation
-@itemize @bullet
+@itemize @bullet{}
@item
Some text for foo.
@@ -6783,9 +6783,9 @@ @node @code{@@itemize}
@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.
+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
@@ -6811,11 +6811,11 @@ @node @code{@@itemize}
@example
@group
-@@itemize @@bullet
+@@itemize @@bullet@{@}
@@item
First item.
-@@itemize @@minus
+@@itemize @@minus@{@}
@@item
Inner item.
@@ -6833,11 +6833,11 @@ @node @code{@@itemize}
This produces:
@quotation
-@itemize @bullet
+@itemize @bullet{}
@item
First item.
-@itemize @minus
+@itemize @minus{}
@item
Inner item.
@@ -9647,10 +9647,6 @@ @node @code{@@bullet}
the closest possible thing to one. An asterisk can also be used.
Here is a bullet: @bullet{}
-When you use @code{@@bullet} in @code{@@itemize}, you do not need to
-type the braces, because @code{@@itemize} supplies them.
-(@pxref{@code{@@itemize}}).
-
@node @code{@@euro}
@nodedescription How to insert the euro currency symbol.
@@ -10098,8 +10094,7 @@ @node Click Sequences
@findex clickstyle
You can change the glyph produced by @code{@@click} with the command
@code{@@clickstyle}, which takes a command name as its single argument
-on the rest of the line, much like @code{@@itemize} and friends
-(@pxref{@code{@@itemize}}). The command should produce a glyph, and
+on the rest of the line. The command should produce a glyph, and
the usual empty braces @samp{@{@}} are omitted. Here's an example:
@example
