Re: @itemize @asis is not well supported

[Gavin Smith]

On Thu, Mar 07, 2024 at 09:49:24AM +0100, Patrice Dumas wrote:
> On Wed, Mar 06, 2024 at 09:54:18PM +0100, Bruno Haible wrote:
> > Gavin Smith wrote:
> > > it is not worth changing and making practically every use of
> > > @itemize in a Texinfo manual being flagged as incorrect, in my opinion.
> > 
> > I agree. Counting the number of existing usages in Debian [1][2]:
> >   - 8753 times '@itemize @bullet' without braces,
> >   - 288 times '@itemize @bullet{}' with braces.
> 
> I understand that it is the current practice, and I do not advocate
> those uses to be flagged as incorrect.  I propose to change the
> documentation such that this use is not proposed as a valid use anymore,
> such that there are braces in future manuals, and also when people
> change manuals they use braces.

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.

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}.