Re: GCC documentation: porting to Sphinx

[Martin Sebor <msebor@gmail.com>]

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.

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