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
