From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ot1-x32f.google.com (mail-ot1-x32f.google.com [IPv6:2607:f8b0:4864:20::32f]) by sourceware.org (Postfix) with ESMTPS id C0B633848415; Fri, 4 Jun 2021 15:10:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C0B633848415 Received: by mail-ot1-x32f.google.com with SMTP id h24-20020a9d64180000b029036edcf8f9a6so9404985otl.3; Fri, 04 Jun 2021 08:10:06 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=nFxxufNIVcFSVIhnZw5pn8UE7bC1dF/R0E4/jaLKFpE=; b=uB+zvVfMHDJnC59gn0R12JIhQCEdj49u60PEHTodeGd2X8qVNxqS/Gwvf4cTwd6bum cD9dvKLMuOb+Q1BWlskSaLreOmxVZiQfUBIYgyVH+ZZz/PrTPop7oyD6dSDwaOUBi2kz oc6cB75RujPb2PKhgJXLQRpfPm7R3QS5GXWl9PnD7biaaG8s6vnwAC+fdie1YkNxjNwc Zi3DP/bidMVQ8Rek/orwPYEXNr/3JVAI4Hif9gATdpQ4R9tLqdWCdq5VmTCmD+aPnTOS 6okSj72F4YdkKdnOnZAdueXjTsyTkCODDr282Va+dDUj2uZy3y77BY9IOV5jRtUYByLP ZLNg== X-Gm-Message-State: AOAM530oss+zjjSfaC0FoAQatwlkzB43gmwwL0Dz6Aw3FwQIdeV4iC5c MmSbSO8xhaAwVVqGciQGNlk= X-Google-Smtp-Source: ABdhPJysT+0lEwwE5ADI1FBNrhRcPsYpSXnQdN4Sq8CSklVxk/evVh9RrpMP+uLHbeeJp/vkW+TerQ== X-Received: by 2002:a9d:5552:: with SMTP id h18mr4334153oti.104.1622819406144; Fri, 04 Jun 2021 08:10:06 -0700 (PDT) Received: from [192.168.0.41] (184-96-226-253.hlrn.qwest.net. [184.96.226.253]) by smtp.gmail.com with ESMTPSA id m19sm472041oov.10.2021.06.04.08.10.04 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 04 Jun 2021 08:10:05 -0700 (PDT) Subject: Re: GCC documentation: porting to Sphinx To: =?UTF-8?Q?Martin_Li=c5=a1ka?= , 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> From: Martin Sebor Message-ID: <7bc0c42f-5cd7-130a-49cf-2df6cb23d6da@gmail.com> Date: Fri, 4 Jun 2021 09:10:04 -0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.2 MIME-Version: 1.0 In-Reply-To: <298e21f2-7d04-7a28-1827-e87f2e70d187@suse.cz> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-2.4 required=5.0 tests=BAYES_00, BODY_8BITS, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, KAM_EU, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham 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: Fri, 04 Jun 2021 15:10:17 -0000 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? 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). 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.) > >> >> 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? 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? 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? 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 >> >