[PATCH] Port GCC documentation to Sphinx

[Martin Sebor]

On 6/29/21 4:09 AM, Martin Liška wrote:
> On 6/28/21 5:33 PM, Joseph Myers wrote:
>> Are formatted manuals (HTML, PDF, man, info) corresponding to this patch
>> version also available for review?
> 
> I've just uploaded them here:
> https://splichal.eu/gccsphinx-final/
> 
> Martin
> 

I think listing the -Wfoo and -Wno-foo (and analogously the -fbar
and -fno-bar) options is an improvement over prior revisions but when
the positive form is the default the text reads funny.  For example:

   -fno-inline

       Do not expand any functions inline apart from those marked
       with the always_inline attribute. This is the default when
       not optimizing.

       Single functions can be exempted from inlining by marking
       them with the noinline attribute.

   -finline

       Default option value for -fno-inline.


I.e., -finline is not what I would describe as a default value for
-fno-inline.

I would suggest to drop the option name from the text describing
the default, and also replace value with setting (it's really not
a value).  It could be as simple as:

   -finline

       Default setting.

Alternatively, to preserve the connection to the alternate setting:

   -finline

       Default setting; overrides -fno-inline.

At some point we talked about also making attributes hyperlinks
(like always_inline and noinline above) but I don't remember
the conclusion.  Are you planning to do that?  (Would handling
it as part of the transition be easier than doing it later?)

Martin