Re: GCC documentation: porting to Sphinx

[Martin Sebor <msebor@gmail.com>]

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/

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.

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

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.

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.

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