GCC documentation: porting to Sphinx

[Martin Liška]

On 6/2/21 10:41 PM, Martin Sebor wrote:
> On 5/31/21 7:25 AM, Martin Liška wrote:
>> Hello.
>>
>> I've made quite some progress with the porting of the documentation and
>> I would like to present it to the community now:
>> https://splichal.eu/scripts/sphinx/
> 

Hello.

Thank you for the review.

> Just a few issues I noticed in the warnings section:
> 
> The headings of some warnings mention the same option twice (e.g.,
> -Wabi, -Wabi, -Wno-abi;  -Wdouble-promotion, -Wdouble-promotion,
> -Wno-double-promotion;  -Winit-self, -Winit-self, -Wno-init-self).
> This looks like a pretty pervasive problem.

You are right, I fixed that.

> 
> Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx.

Yes. Good reason for that is that Sphinx can then generated properly links
to the current non-documented version of the option. Hope it's improvement
over the current situation?

> 
> The headings of some other warnings also mention options that are
> only remotely related to them.  E.g., -Wformat has all these:
> 
>    -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat=
> 
> (I see the same problem in the attributes section where the headings
> for some attributes include option names).
> 
> That seems quite puzzling.  I assume it's a consequence of having
> index entries for the related options, but I don't think making
> them visible in the headings is helfpful.

Oh, you are right. It was consequence of wrong parsing of index entries.
It should be fixed now.

> 
> Headings that in the manual today include a level like
> 
>    -Wformat-overflow
>    -Wformat-overflow=level
> 
> don't mention the level in the Spinx manual:
> 
>    -Wformat-overflow, -Wno-format-overflow
> 
> When the /level/ is then discussed in the rest of the text it's
> not clear what it refers to.

Should be also fixed now.

Can you please take a look at the current output and give me a feedback?
Thanks,
Martin

> 
> Martin
> 
>>
>> Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]).
>> It's built on the devel/sphinx GCC branch which I periodically with the master branch. One can
>> see the current source .rst files here: [3].
>>
>> Changes made since the last time:
>> - a shared content is factored out ([4])
>> - conditional build is fully supported (even for shared parts)
>> - manual pages look reasonable well
>> - folders are created for files which have >= 5 TOC tree entries
>> - various formatting issues were resolved
>> - baseconf.py reads BASE-VER, DEV-PHASE, .. files
>>
>> I've got couple of questions:
>>
>> 1) Do we have to you the following cover text?
>>         Copyright (c) 1988-2020 Free Software Foundation, Inc.
>>
>>         Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public
>>         License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below).  A copy of the license is included in the gfdl(7) man page.
>>
>>         (a) The FSF's Front-Cover Text is:
>>
>>              A GNU Manual
>>
>>         (b) The FSF's Back-Cover Text is:
>>
>>              You have freedom to copy and modify this GNU Manual, like GNU
>>              software.  Copies published by the Free Software Foundation raise
>>              funds for GNU development.
>>
>> 2) Do we want to generate fsf-funding, gpl and gfdl manual pages?
>> 3) Do we want to preserve the current strange copy mechanism for ./gcc/doc/tm.texi.in ?
>> 4) Do we want a copyright header for the created .rst files?
>>
>> Thoughts?
>> Thanks,
>> Martin
>>
>> [1] https://github.com/davidmalcolm/texi2rst
>> [2] https://github.com/davidmalcolm/texi2rst/actions
>> [3] https://github.com/marxin/texi2rst-generated/tree/master/sphinx
>> [4] https://github.com/marxin/texi2rst-generated/tree/master/sphinx/share
>