On 4/10/19 5:13 AM, Jonathan Wakely wrote:
For options that can be used as -foo or -foo=level we have a variety
of different styels for documenting what the default level is. See
below for several examples. I find this a bit confusing when try to
see what it means to use the option without a level.
Do we want to pick a style and try to be consistent?
I think part of the problem here is that it collides with the existing
convention that we document the -foo form for options that default to
off and the -no-foo form for options that default to on, and we probably
have instances of both flavors that were originally binary options but
now take an optional level. Plus people tack on to the documentation
incrementally for new options and don't always check for or copy the
style of documentation for similar option syntax elsewhere.
I suspect anything we do will eventually get bit-rotten anyway, but if
you want a convention, I'd propose that we always document -foo=level as
the primary form and explicitly list whichever of -foo and/or -no-foo
are also supported (regardless of the default), with information in the
text about what level they correspond to, what the default is, etc.
E.g. roughly following this organization:
@item -foo=@var{level}
@itemx -foo
@itemx -no-foo
@opindex foo
This option controls....
The @var{level} may be one of....
@option{-foo} without a @var{level} is equivalent to....
@option{-fno-foo} is equivalent to....
The default is.... [and/or information about what setting is implied by
other options].
-Sandra
