On Tue, Mar 12, 2024 at 11:40 AM Gavin Smith <[email protected]>
wrote:
> 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.)
--
Ray
