From: "Martin Liška" <mliska@suse.cz>
To: Martin Sebor <msebor@gmail.com>,
David Malcolm <dmalcolm@redhat.com>,
gcc-patches@gcc.gnu.org
Cc: GCC Development <gcc@gcc.gnu.org>,
"Joseph S. Myers" <joseph@codesourcery.com>
Subject: Re: GCC documentation: porting to Sphinx
Date: Thu, 10 Jun 2021 11:07:21 +0200 [thread overview]
Message-ID: <9fbfa220-0708-bc7a-6e6b-0865d413d1ed@suse.cz> (raw)
In-Reply-To: <7bc0c42f-5cd7-130a-49cf-2df6cb23d6da@gmail.com>
On 6/4/21 5:10 PM, Martin Sebor wrote:
> On 6/3/21 4:56 AM, Martin Liška wrote:
>> 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.
>
> Looks good.
>
>>
>>>
>>> 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?
Hello.
Back to this after some thinking.
>
> I think the linking is helpful. But for warnings, the documented
> convention is to only mention the one that's not the default:
>
> This manual lists only one of the two forms, whichever is not
> the default.
>
> so including both blurs this (IMO rather subtle) distinction.
> In addition, in options whose description says something like
> "This warning is enabled by -Wall." it's now less clear which
> one is the one the "this" refers to (see for example
> -Wchar-subscripts).
Yes, that's really confusing and we should likely explicitly document
both options as shown here (-Wno-shift-overflow3):
https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3
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.
>
> If the heading can't be changed at a minimum we'll need to update
> the convention above, e.g., by saying that the first option mentions
> is the default. But again, I think this is too subtle for the casual
> reader to pick up on. The fact that the sentence quoted above appears
> under -Wfatal-errors doesn't help. We should also work on updating
> the "This option is in -Wall." either to name the specific option
> it refers to, or consider moving that into a Note box like the one
> listing the languages the option applies to.)
Yes, we should explicitly mark one of them as default value,
something like "Default option value for -Wshift-overflow3."?
And the corresponding counter-part should have "Enabled by -Wall.". I'm not fully
convinced about usage of note as it's quite big visual component.
>
>>
>>>
>>> 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.
>
> Looks good.
>
>>
>>>
>>> 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.
>
> Also looks good.
>
>>
>> Can you please take a look at the current output and give me a feedback?
>
> I noticed another minor issue that may already have been pointed
> out by someone else. Under -Wall (and -Wextra), some option names
> are prefixed by :option: (e.g., (only with :option:-O2``). Looks
> like some sort of a transcription bug?
Yes, that should be fixed now. Most comment root cause is that some inline
roles are wrapped (that's not supported).
>
> And a couple of questions:
>
> References to options with an argument like -Warray-bounds=1 are
> rendered in a way that makes it look like there's a space before
> the equals: -Warray-bounds =1, with the =1 being in a different
> color and not part of the hyperlink. Is there a way to make it look
> like there is no space?
Likely not. That's the best I was able to come up with. Reason why the '=1'
argument is in :samp: is that :option:`-Wfoo=123` does not properly generate link
to the option directive. And there's actually no space in HTML, it's only slightly
visually separated and PDF version is fine for me.
>
> I like how options are automatically linked, and I'd like to see
> the same for other references like to attributes. Can that be
> automated as part of the migration or should we/I try to tackle
> it in a followup?
Right now, I abuse a bit .. option:: my_attribute directive for them.
For the future, yes, one can make a link to them with :option:`my_attribute`.
Thanks for useful feedback!
Martin
>
> In any event, thanks for working so hard on making this turn out
> great!
>
> Martin
>
>> 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
>>>
>>
>
next prev parent reply other threads:[~2021-06-10 9:07 UTC|newest]
Thread overview: 113+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <1446990946.2994.192.camel@surprise>
[not found] ` <e7f490fc-ab76-5bc5-5e94-1d9f00f34b62@suse.cz>
2021-05-13 11:45 ` RFC: Sphinx for GCC documentation Martin Liška
2021-05-31 13:25 ` GCC documentation: porting to Sphinx Martin Liška
2021-05-31 15:49 ` Michael Matz
2021-06-01 7:31 ` Martin Liška
2021-06-01 13:31 ` Michael Matz
2021-06-02 7:36 ` Martin Liška
2021-06-02 16:05 ` Joel Sherrill
2021-06-02 16:44 ` Joseph Myers
2021-06-03 12:26 ` Martin Liška
2021-06-03 17:16 ` Joseph Myers
2021-06-04 7:27 ` Martin Liška
2021-06-02 17:27 ` Joseph Myers
2021-06-10 14:06 ` Martin Liška
2021-06-10 16:49 ` Joseph Myers
2021-06-11 14:33 ` Martin Liška
2021-06-11 15:50 ` Joseph Myers
2021-06-11 18:48 ` Koning, Paul
2021-06-23 13:13 ` Martin Liška
2021-06-23 16:00 ` Joseph Myers
2021-06-24 14:08 ` Martin Liška
2021-06-25 13:11 ` Martin Liška
2021-06-25 13:14 ` Martin Liška
2021-06-28 10:23 ` Arnaud Charlet
2021-06-28 10:44 ` Martin Liška
2021-06-29 15:54 ` Arnaud Charlet
2021-06-30 7:52 ` Martin Liška
2021-08-10 15:43 ` Martin Liška
2021-08-27 9:31 ` Martin Liška
2021-06-28 12:01 ` [PATCH] Port GCC documentation " Martin Liška
2021-06-28 15:33 ` Joseph Myers
2021-06-29 10:09 ` Martin Liška
2021-06-29 10:50 ` Richard Earnshaw
2021-06-30 4:47 ` Martin Liška
2021-06-30 10:14 ` Richard Earnshaw
2021-06-30 11:58 ` Martin Liška
2021-06-29 16:57 ` Eli Zaretskii
2021-06-29 18:01 ` Eli Zaretskii
2021-06-30 10:11 ` Martin Liška
2021-06-30 10:46 ` Martin Liška
2021-06-30 13:09 ` Eli Zaretskii
2021-07-01 12:44 ` Martin Liška
2021-07-01 13:33 ` Eli Zaretskii
2021-07-01 14:14 ` Martin Liška
2021-07-01 15:06 ` Michael Matz
2021-07-02 9:40 ` Martin Liška
2021-07-02 10:32 ` Eli Zaretskii
2021-07-01 15:44 ` Eli Zaretskii
2021-07-01 16:04 ` Martin Liška
2021-07-01 16:58 ` Eli Zaretskii
2021-07-02 9:30 ` Martin Liška
2021-07-02 10:31 ` Eli Zaretskii
2021-07-02 13:23 ` Martin Liška
2021-07-02 23:53 ` Hans-Peter Nilsson
2021-07-05 9:17 ` Richard Sandiford
2021-07-05 12:14 ` Eli Zaretskii
2021-07-05 13:03 ` Richard Sandiford
2021-07-12 13:25 ` Benefits of using Sphinx documentation format Martin Liška
2021-07-12 13:39 ` Eli Zaretskii
2021-07-12 13:53 ` Jonathan Wakely
2021-07-12 14:05 ` Jonathan Wakely
2021-07-12 14:16 ` Eli Zaretskii
2021-07-12 14:34 ` Martin Liška
2021-07-12 17:09 ` Eli Zaretskii
2021-07-12 14:12 ` Eli Zaretskii
2021-07-12 14:30 ` Martin Liška
2021-07-12 14:54 ` Matthias Kretz
2021-07-12 17:03 ` Eli Zaretskii
2021-07-12 17:15 ` Jonathan Wakely
2021-07-12 17:23 ` Eli Zaretskii
2021-07-12 17:33 ` Jonathan Wakely
2021-07-13 6:24 ` Richard Biener
2021-07-13 11:52 ` Eli Zaretskii
2021-07-13 12:46 ` Richard Biener
2021-07-13 12:55 ` Eli Zaretskii
2021-08-09 12:12 ` Martin Liška
2021-07-13 14:19 ` Jonathan Wakely
2021-07-12 14:52 ` Jonathan Wakely
2021-07-12 14:54 ` Jonathan Wakely
2021-07-12 17:14 ` Eli Zaretskii
2021-07-12 15:03 ` Jonathan Wakely
2021-07-12 16:00 ` Gavin Smith
2021-07-12 16:15 ` Jonathan Wakely
2022-07-05 12:27 ` Copiable anchor links in gcc manual Gavin Smith
2022-07-05 13:28 ` Jonathan Wakely
2021-07-12 14:37 ` Benefits of using Sphinx documentation format Martin Liška
2021-07-12 17:12 ` Eli Zaretskii
2021-07-12 16:36 ` David Malcolm
2021-07-12 18:23 ` Koning, Paul
2021-06-30 12:26 ` [PATCH] Port GCC documentation to Sphinx Martin Liška
2021-06-30 13:28 ` Martin Liška
2021-06-30 13:38 ` Eli Zaretskii
2021-06-30 14:04 ` Martin Liška
2021-06-30 15:43 ` Eli Zaretskii
2021-07-01 12:31 ` Martin Liška
2021-07-12 17:18 ` Martin Sebor
2021-08-09 12:18 ` Martin Liška
2021-07-13 14:54 ` Tamar Christina
2021-08-09 13:29 ` Martin Liška
2021-06-02 20:41 ` GCC documentation: porting " Martin Sebor
2021-06-03 10:56 ` Martin Liška
2021-06-04 15:10 ` Martin Sebor
2021-06-10 9:07 ` Martin Liška [this message]
2021-06-10 13:18 ` Martin Liška
2021-06-10 23:48 ` Martin Sebor
2021-06-11 14:34 ` Martin Liška
2021-06-04 7:55 ` RFC: Sphinx for GCC documentation Tobias Burnus
2021-06-04 14:24 ` Koning, Paul
2021-06-07 13:30 ` Martin Liška
2021-06-07 21:26 ` Bernhard Reutner-Fischer
2021-06-08 7:43 ` Martin Liška
2021-06-07 13:28 ` Martin Liška
2021-06-07 14:19 ` Tobias Burnus
2021-06-10 10:32 ` Martin Liška
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9fbfa220-0708-bc7a-6e6b-0865d413d1ed@suse.cz \
--to=mliska@suse.cz \
--cc=dmalcolm@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=gcc@gcc.gnu.org \
--cc=joseph@codesourcery.com \
--cc=msebor@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).