Documentation style for options with optional levels

[Sandra Loosemore]

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