Re: @itemize @asis is not well supported

[Patrice Dumas]

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

bullet_braces_addition_doc.diff
Description: Text Data