Documentation style for options with optional levels

[Jonathan Wakely]

On 10/04/19 08:42 -0400, Nathan Sidwell wrote:
>On 4/10/19 7: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?
>
>yes?

Thought so. "Somebody" should do something about this ;-)


>All the examples you give leave something to be desired.
>
>>For -Wformat-overflow we show the option with and without the level:
>>
>> Â @item -Wformat-overflow
>> Â @itemx -Wformat-overflow=1
>> Â @opindex Wformat-overflow
>> Â @opindex Wno-format-overflow
>> Â Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}
>
>The @item is the clearest to read, and also the most accurate as it 
>shows you can provide it without a level.  But from that snippet 
>there's no indication what not giving a level gets you.  There needs 
>to be some words somewhere to say what it maps to.
>
>>For -Wshift-overflow we use prose to say what omitting the level
>>means:
>>
>> Â @item -Wshift-overflow=1
>> Â This is the warning level of @option{-Wshift-overflow} and is enabled
>> Â by default in C99 and C++11 modes (and newer).
>
>.. for example that, I can't tell if I can say just -Wshift-overflow 
>and get level 1, or if I'll get level 1 whatever unless I say 
>-Wno-shift-overflow
>
>>For -Warray-bounds we list both options separately, and then also list
>>the forms with levels and say what no level means:
>>
>> Â @item -Warray-bounds
>> Â @itemx -Warray-bounds=@var{n}
>> Â @opindex Wno-array-bounds
>> Â @opindex Warray-bounds
>> Â This option is only active when @option{-ftree-vrp} is active
>> Â (default for @option{-O2} and above). It warns about subscripts to arrays
>> Â that are always out of bounds. This warning is enabled by @option{-Wall}.
>>
>> Â @table @gcctabopt
>> Â @item -Warray-bounds=1
>> Â This is the warning level of @option{-Warray-bounds} and is enabled
>> Â by @option{-Wall}; higher levels are not, and must be explicitly 
>>requested.
>
>In context with the other levels, I see that is trying to tell you 
>that 1 is the default, but it's unclear.  My first reading was that 1 
>gets you a warning level, (with the implication that 2 got you an 
>error level or something?)

Right. Too often you have to try and infer what it's saying, and when
every case is presented differently you can't even apply the same
inferences to different options!

If we decide on a way to document these cases that is clear and
unambiguous, I'll volunteer to go through the existing docs and usee
that style.