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 22B013861821; Thu, 10 Jun 2021 14:06:46 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 22B013861821 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 A06B41FD37; Thu, 10 Jun 2021 14:06:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623334004; 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=X1CiIq4kIKrnCLLfRgnei4vFGNFddB+TsWbKSoSXsTM=; b=ZB/Q45lVo/ESGTIkQi9ay/IStnyGN+q5o60J/gMS1B4LSpxRs94J6OLyxgTwV/lIAKaHM2 pw1WkOaCSTdlSAE5p+kwC4pDWW1DnuUcTiPVZYNa4RDfqWabyUZmxX+Md+GltS2/4/NIi+ zrdZ26GfhdK93LDfi7/NJZVKfTG/9ew= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623334004; 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=X1CiIq4kIKrnCLLfRgnei4vFGNFddB+TsWbKSoSXsTM=; b=QC6Sx0t7s81N74zgwRq4+clPbOp94Wp8kerGbr1R0NPeKOkeFH2ZovgdDxJ7C9XZfmAzpx 4T5VzFnT7l6l/UAQ== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 7B14F118DD; Thu, 10 Jun 2021 14:06:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1623334004; 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=X1CiIq4kIKrnCLLfRgnei4vFGNFddB+TsWbKSoSXsTM=; b=ZB/Q45lVo/ESGTIkQi9ay/IStnyGN+q5o60J/gMS1B4LSpxRs94J6OLyxgTwV/lIAKaHM2 pw1WkOaCSTdlSAE5p+kwC4pDWW1DnuUcTiPVZYNa4RDfqWabyUZmxX+Md+GltS2/4/NIi+ zrdZ26GfhdK93LDfi7/NJZVKfTG/9ew= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1623334004; 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=X1CiIq4kIKrnCLLfRgnei4vFGNFddB+TsWbKSoSXsTM=; b=QC6Sx0t7s81N74zgwRq4+clPbOp94Wp8kerGbr1R0NPeKOkeFH2ZovgdDxJ7C9XZfmAzpx 4T5VzFnT7l6l/UAQ== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id AqT9HHQcwmBdWgAALh3uQQ (envelope-from ); Thu, 10 Jun 2021 14:06:44 +0000 Subject: Re: GCC documentation: porting to Sphinx To: Joseph Myers Cc: David Malcolm , gcc-patches@gcc.gnu.org, GCC Development References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz> Date: Thu, 10 Jun 2021 16:06:44 +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: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, 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 14:06:48 -0000 On 6/2/21 7:27 PM, Joseph Myers wrote: > 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. Yes, I'm aware of various cross-manual links that are currently not working. It will likely require an extension called Intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html > > * "` 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. Yes, I fixed various :samp:, :option: leftovers all over the documentation. > > * 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. Hm, I think the generated PDF properly uses a fixed-width font for option names, commands and so one. Moreover, option directives are bold, while links to them use normal font. I see the default font selection made by Sphinx readable. > > 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". I fixed various these issues. > > 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. Oh yeah. Apparently, we can use "smart quotes" (-- and ---) for dashes: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes Fixed that in the current version. > > 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 /). Good point, also fixed. > > 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. As discussed with Martin Sebor, I emitted non-default option directive. > > 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). Also fixed. > > 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. Clean up these. > > 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). I fixed all code-block warnings. Some of JSON syntax highlighting was not working because the JSON syntax was invalid. Should be fine: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-control-diagnostic-messages-formatting.html#cmdoption-fdiagnostics-format > >> - 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? Sure: 1) documentation fragments in target.def I've got a script that rewrites them to RST format and we'll use the slightly modified gcc/genhooks.c for replacement. 2) comments Are preserved by the conversion tool. 3) man pages support and @ignore That's done, we have shared content and conditional build (..only directive). 4) support for BASE-VER, DATESTAMP, DEV-PHASE It's read right now in baseconf.py, we need to add support for bugurl and package_version, it won't be difficult. > > 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. Added that to copyright.rst file. > >> 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. Done. > >> 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. As mentioned, it will be supported. > >> 4) Do we want a copyright header for the created .rst files? > > Yes, all source files should have a copyright header. > Done. @Joseph: May I ask you for another round of review? The generated pages are quite fine, I addressed various smaller issues. Hopefully we are quite close to something that can be send to gcc-patches. Another set of questions I have: 1) Can we organize the new documentation in $gccroot/doc folder similarly to what I have in texi2rst-generated repo? Would be beneficial as we can have a single Makefile and shared content will be in a same depth to the individual manuals. 2) About libiberty - who's in charge of the library? Is it GCC community? I'm asking if we want to migrate to Sphinx as well? Thanks, Martin