From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by sourceware.org (Postfix) with ESMTPS id 15DB73AAAC03; Thu, 10 Jun 2021 09:07:23 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 15DB73AAAC03 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.cz Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.cz Received: from imap.suse.de (imap-alt.suse-dmz.suse.de [192.168.254.47]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id BE7631FD37; Thu, 10 Jun 2021 09:07:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623316041; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=P4QfeKU9GjlcshqvtgMJHhP47uvMuw88qHE4qnAU38o=; b=x8ctKqqujo7VGoNjzBEBKRYGjoE1/aLs5kb5P8Ujf4bJGeOqjYM9vHFmboyr2L/AkQHYmZ ihCaKehtkk9s7FusJtHBhV3ngXhh9h7a2kDQt3rHsiM4pdsRAJPLto8AojJ959eaN89D4z ARcDe/imRoRT+Iaw1lPh+0dZGJjyA9Q= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623316041; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=P4QfeKU9GjlcshqvtgMJHhP47uvMuw88qHE4qnAU38o=; b=Ey2/5uoyNuQwLAeCo4B9WV8omVfp76YQcc4htNXTYw38ZII9kt6JQDg8JXzv1G9EuVg27o 0WA969PKkUXa7hAg== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 94D56118DD; Thu, 10 Jun 2021 09:07:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623316041; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=P4QfeKU9GjlcshqvtgMJHhP47uvMuw88qHE4qnAU38o=; b=x8ctKqqujo7VGoNjzBEBKRYGjoE1/aLs5kb5P8Ujf4bJGeOqjYM9vHFmboyr2L/AkQHYmZ ihCaKehtkk9s7FusJtHBhV3ngXhh9h7a2kDQt3rHsiM4pdsRAJPLto8AojJ959eaN89D4z ARcDe/imRoRT+Iaw1lPh+0dZGJjyA9Q= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623316041; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=P4QfeKU9GjlcshqvtgMJHhP47uvMuw88qHE4qnAU38o=; b=Ey2/5uoyNuQwLAeCo4B9WV8omVfp76YQcc4htNXTYw38ZII9kt6JQDg8JXzv1G9EuVg27o 0WA969PKkUXa7hAg== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id htmAI0nWwWAELgAALh3uQQ (envelope-from ); Thu, 10 Jun 2021 09:07:21 +0000 Subject: Re: GCC documentation: porting to Sphinx To: Martin Sebor , David Malcolm , gcc-patches@gcc.gnu.org Cc: GCC Development , "Joseph S. Myers" References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> <298e21f2-7d04-7a28-1827-e87f2e70d187@suse.cz> <7bc0c42f-5cd7-130a-49cf-2df6cb23d6da@gmail.com> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <9fbfa220-0708-bc7a-6e6b-0865d413d1ed@suse.cz> Date: Thu, 10 Jun 2021 11:07:21 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.10.2 MIME-Version: 1.0 In-Reply-To: <7bc0c42f-5cd7-130a-49cf-2df6cb23d6da@gmail.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-3.2 required=5.0 tests=BAYES_00, BODY_8BITS, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 10 Jun 2021 09:07:25 -0000 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 >>> >> >