From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ot1-x32b.google.com (mail-ot1-x32b.google.com [IPv6:2607:f8b0:4864:20::32b]) by sourceware.org (Postfix) with ESMTPS id D3D1E3854812; Wed, 2 Jun 2021 20:41:51 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D3D1E3854812 Received: by mail-ot1-x32b.google.com with SMTP id 36-20020a9d0ba70000b02902e0a0a8fe36so3668772oth.8; Wed, 02 Jun 2021 13:41:51 -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=6cH5iQILMuUCpY8YfRiArPuFQF61l7UL4OZsAtUlJ1I=; b=ZZ2OiVhyeX3v/O3wg6gKo5W8Vz7h6hGZSZlYHd8X43sV3MmGnlIDkMfYGwUtv+Pgyf z7iVKJgIaf4Hz774ddDg/6paPwciEU7xB4t/Io5sOMGfwFzjTOsUSRjLuYAt4CxDDb55 5NluRp7vAeCWw2ybsDWuZoaNz+o1XzlBVcx5TYkCStAMmH8cYtvhxrbxLJcr6T1AZhWU 6EsqnkS3aN+n3JhT4MkM1gluZufK/duAc3xXhnHd7GdMeVI5T8UWlp+jbjK/Nu79MUVN vNZXVTpRswSS8akqXpDEtUrBxztDAUYwrm/572YyrYfZdH7IyZCJAFJG5/VtrsoY9OQw whVA== X-Gm-Message-State: AOAM530lv0TUXO68rmFPcHJ1kUJF6w0HwrPlfTLdqwJg0XtrC1GHKad6 17nINPeboO98y+V8LxQcq9g= X-Google-Smtp-Source: ABdhPJyBRQjXVQO/xVhqmNBVQBsAC0QeyJaWbOvlzo7Mi1KnDo9oP0gaSPSxZr/TC9/YXM0QwgmYsQ== X-Received: by 2002:a9d:3436:: with SMTP id v51mr28305838otb.346.1622666511223; Wed, 02 Jun 2021 13:41:51 -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 12sm207645ooy.0.2021.06.02.13.41.50 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 02 Jun 2021 13:41:50 -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> From: Martin Sebor Message-ID: Date: Wed, 2 Jun 2021 14:41:49 -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: <3a2a573b-5185-fff5-f9da-6e5e39953ad6@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.2 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: Wed, 02 Jun 2021 20:41:54 -0000 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