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 haven't been following too closely, but I think the manual should only have examples of recommended practice. If @bullet{} is the recommended way, then examples should only have that. If the parser is lax and not enforcing this, then that's ok. Just don't confuse people that @bullet and @bullet{} are both valid ways. (Well, unless you are really saying both are valid now and in the probable future, in which case, ignore me.)