GCC documentation: porting to Sphinx

[Martin Liška]

On 6/11/21 1:48 AM, Martin Sebor wrote:
> On 6/10/21 7:18 AM, Martin Liška wrote:
>> On 6/10/21 11:07 AM, Martin Liška wrote:
>>> Doing that, one has 2 unique links, that would be needed for get_option_url function.
>>> Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work.
>>
>> And I've actually did the transformation and one can see it e.g. here:
>> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wprio-ctor-dtor 
> 
> I find the style you have below right now clearer than keeping both
> options in the same heading and adding a Note explaining the default
> etc.  I.e., this
> 
>    _________________
>    -Wchar-subscripts
> 
>      Warn if an array subscript has type char. This is a common cause
>      of error, as programmers often forget that this type is signed on
>      some machines. This warning is enabled by -Wall.
> 
>    ____________________
>    -Wno-char-subscripts
> 
>     Default option value for -Wchar-subscripts.

Yes, fully agree with you!

Thanks,
Martin

> 
> on this page right now:
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wchar-subscripts
> 
> seems better than this:
> 
>    _________________________________________________________
>    -Wno-shift-overflow, -Wshift-overflow=n, -Wshift-overflow
> 
>      +--------------------------------------------------------------+
>      | (!) Note                                                     |
>      +---------------------------------------------------------------
>      | Default value is -Wno-shift-overflow, -Wshift-overflow is    |
>      | enabled by -Wall.                                            |
>      +--------------------------------------------------------------+
> 
>      These options control warnings about left shift overflows.
> 
> and also better than the alternative with (non-default) after the option
> in the heading.
> 
> https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3
> 
> Martin
> 
>>
>>
>> Martin
>