From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from esa3.mentor.iphmx.com (esa3.mentor.iphmx.com [68.232.137.180]) by sourceware.org (Postfix) with ESMTPS id 786983985436; Wed, 2 Jun 2021 17:27:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 786983985436 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com IronPort-SDR: +mM9yF4sKu78ZMbfg/c4T01Gf9gRhI5/9kBohRbSIXMb8BMkpc2q2Ly9WheaduOz+3zxW1Wd81 1vxyYqxz9dl1Sln9eP4R1YI6zlzRmWpRjk+eeEsVgHYbMcCeJ+EbB2YVce+h7IDi3Fg/oRnXp2 a/lk0WWduFSmU1kn8W7tOMyDyuP5BO3gFCxlzA8WnjJHwdoQmqKs2+Lmmb4n39oNv+4KOPbgC0 keOOHIGBvXs1IIPeQ4sY9VteorGaQJw2dINawaO4d7jm9efGdkQ7bZs3Tg/qaO2gYVaSMmGSFO 3pw= X-IronPort-AV: E=Sophos;i="5.83,242,1616486400"; d="scan'208";a="61929870" Received: from orw-gwy-02-in.mentorg.com ([192.94.38.167]) by esa3.mentor.iphmx.com with ESMTP; 02 Jun 2021 09:27:24 -0800 IronPort-SDR: pFrlklgpKAOsfW46q1nysZbSdzujUqRaefSCtdy7EtJrWjLzwwZu3eZ9wZca+v4ju4bYtFaWcu d3Y/NLTT/t+9Fk6wP6ajR1vET+LWLrH055s90/6x3gGebDJnjttLz22BfRq585gSMO9gSDlDst eXbdnDfvxHShRU3qU7GX59w1L/y1jvMBrGGNfDKxD/fPLJpd5K+JuXxQPkacjHascSVbMXdfRs tNhU9K9cywJFlvmp+giabGmxeG2NuwfJ/MV1eWW+Ta43MSTF1qRT1IVBh/luPldJlQB5pP8tDO b0k= Date: Wed, 2 Jun 2021 17:27:19 +0000 From: Joseph Myers X-X-Sender: jsm28@digraph.polyomino.org.uk To: =?ISO-8859-15?Q?Martin_Li=A8ka?= CC: David Malcolm , , GCC Development Subject: Re: GCC documentation: porting to Sphinx In-Reply-To: <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> Message-ID: References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> User-Agent: Alpine 2.22 (DEB 394 2020-01-19) MIME-Version: 1.0 X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) X-Spam-Status: No, score=-3120.6 required=5.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, KAM_EU, KAM_SHORT, SPF_HELO_PASS, 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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8BIT X-Content-Filtered-By: Mailman/MimeDel 2.1.29 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 17:27:27 -0000 On Mon, 31 May 2021, Martin Liška wrote: > https://splichal.eu/scripts/sphinx/ Looking at some examples there: https://splichal.eu/scripts/sphinx/gcc/_build/html/c-implementation-defined-behavior/preprocessing-directives.html has some conversion problems: * "See Implementation-defined behavior, for details of these aspects of implementation-defined behavior." is missing the link to the relevant section of the cpp manual that's present in the Texinfo source. * "` character before the :samp:`" is a misconversion (whether from Texinfo to RST or from RST to HTML) of the Texinfo source @samp{\} character before the @samp{\} which will need to be fixed. * The corresponding PDF has the same issues as above (so probably they are issues with the conversion to RST, not with Sphinx itself). In addition, the PDF manual ought to be using fixed-width fonts for literal code, command-line options, etc., just like the HTML manual, and the Texinfo-generated PDF manual, are. https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/passing-options-to-the-assembler.html shows headings such as "-Wa,option, -Wa". The ", -Wa" doesn't make sense, this option is just "-Wa,option". https://splichal.eu/scripts/sphinx/gcc/_build/html/gcov-a-test-coverage-program.html has a hyphen between "gcov" and "a Test Coverage Program" in the heading. It should be an em dash, as in Texinfo. https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/c%2B%2B-language.html has doubled slashes in various URLs where the Texinfo source has /@/ (Texinfo @/ means "allow line break", it should not be translated to /). https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/machine-dependent-options/aarch64-options.html shows different formatting for the headings for "-mlow-precision-div, -mno-low-precision-div" and "-mtrack-speculation -mno-track-speculation". The formatting should be identical. The only difference in the Texinfo source seems to be that the latter is missing @opindex directives. And while it's a bug in the Texinfo source that those directives are missing, the presence or absence of index entries should not affect the formatting of the documentation for those options. On that same page, the output for -march=name is broken, containing a literal :samp:{feature} (in general, checking for any places where RST directives such as :samp: appear in the HTML output might be a good idea to look for broken conversions). The Texinfo source here has @option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}} (where the use of @r{...} is to put the {}[]* characters in a variable-width font, since they are not literally part of the option, while the other characters that are literally part of the option should be in a variable-width font). https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/references-for-other-languages.html has literal unconverted "@c man" and "@include" and other Texinfo directives. Searching for such things in the HTML output (or the RST sources) is a good idea, just like searching for literal RST directives in the HTML output, to find other such conversion bugs. https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options.html says "See option-index", another case with a link that didn't get converted properly. It also has raw :samp: uses indicating a misconversion. I'm not sure how you're determining languages for code-block, but https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-control-diagnostic-messages-formatting.html certainly shows some cases where they have been misidentified (e.g. random C++ keywords highlighted in the default GCC_COLORS, some JSON being highlighted as such but other JSON not). > - 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 Could you give more detailed descriptions of how each of the various issues I listed in 2015 are addressed here? https://gcc.gnu.org/legacy-ml/gcc-patches/2015-11/msg01139.html > 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. We need to keep the Cover Texts and Invariant Sections, in the absence of FSF approval to remove them. > 2) Do we want to generate fsf-funding, gpl and gfdl manual pages? Yes, this is how the set of man pages as a whole keeps the invariant sections. > 3) Do we want to preserve the current strange copy mechanism for > ./gcc/doc/tm.texi.in ? Yes, this is how we ensure we have both GPL and GFDL copies of the target hook documentation checked in and that someone copying from one place to another makes sure they have any relevant permissions. > 4) Do we want a copyright header for the created .rst files? Yes, all source files should have a copyright header. -- Joseph S. Myers joseph@codesourcery.com