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 B21D3397C875; Fri, 2 Jul 2021 09:30:03 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org B21D3397C875 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 9672820072; Fri, 2 Jul 2021 09:30:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625218202; 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=eJyi2ra8q+JKISSzYX0stomdsBGPzu5AxPQtZcMk8mM=; b=QYwQl73gneDUq+a15AhRDOnaqXzhHQcyOHyWyoZowBokpM2Z28DBezm9X7s/WDT3QnWy8r xdrDOqbMKf7zJZ0AC4lf1Svy8jgPkGtumUUjpFl01yZJO9Kl/uv9wEPBzdOaRqNbthS9gs BkfbPswT8Wcz20lw5uED+yRzFMNSwFs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625218202; 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=eJyi2ra8q+JKISSzYX0stomdsBGPzu5AxPQtZcMk8mM=; b=+/q+cLXF9v/+6HM0Im/1M5aCZfCv7a6nO9QSJGmwVjH9Qx7qXjG+xZEsjkxoCpGGqxbRFR FkZIGigBIWO7XeCw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 7048411CD6; Fri, 2 Jul 2021 09:30:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625218202; 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=eJyi2ra8q+JKISSzYX0stomdsBGPzu5AxPQtZcMk8mM=; b=QYwQl73gneDUq+a15AhRDOnaqXzhHQcyOHyWyoZowBokpM2Z28DBezm9X7s/WDT3QnWy8r xdrDOqbMKf7zJZ0AC4lf1Svy8jgPkGtumUUjpFl01yZJO9Kl/uv9wEPBzdOaRqNbthS9gs BkfbPswT8Wcz20lw5uED+yRzFMNSwFs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625218202; 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=eJyi2ra8q+JKISSzYX0stomdsBGPzu5AxPQtZcMk8mM=; b=+/q+cLXF9v/+6HM0Im/1M5aCZfCv7a6nO9QSJGmwVjH9Qx7qXjG+xZEsjkxoCpGGqxbRFR FkZIGigBIWO7XeCw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id V1uSGprc3mBxQQAALh3uQQ (envelope-from ); Fri, 02 Jul 2021 09:30:02 +0000 Subject: Re: [PATCH] Port GCC documentation to Sphinx To: Eli Zaretskii Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org References: <1446990946.2994.192.camel@surprise> <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz> <5ffe3e32-ece0-a1b4-1fcf-e35177fa80b5@suse.cz> <87489d9a-44e2-411c-3f3a-534d07e78b95@suse.cz> <0866a0ea-c846-ea5e-ac7a-d1c8f106cc45@suse.cz> <5bb9a10d-f3b9-f16a-7430-bbae2d4978e2@suse.cz> <2f60f602-5d88-7674-9620-2172748664c5@suse.cz> <83a6n8obh4.fsf@gnu.org> <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> <83pmw3mrcg.fsf@gnu.org> <83k0makvk7.fsf@gnu.org> <56699e91-9e02-102e-4277-af8823cf3145@suse.cz> <83h7hekpi9.fsf@gnu.org> <79939338-7f4f-121c-5fa9-316ae0fc47aa@suse.cz> <838s2qkm2i.fsf@gnu.org> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Fri, 2 Jul 2021 11:30:02 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: <838s2qkm2i.fsf@gnu.org> 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_SHORT, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) 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, 02 Jul 2021 09:30:05 -0000 On 7/1/21 6:58 PM, Eli Zaretskii wrote: >> Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org >> From: Martin Liška >> Date: Thu, 1 Jul 2021 18:04:24 +0200 >> >>> Emacs doesn't hide the period. But there shouldn't be a period to >>> begin with, since it's the middle of a sentence. The correct way of >>> writing this in Texinfo is to have some punctuation: a comma or a >>> semi-colon, after the closing brace, like this: >>> >>> This is the warning level of @ref{e,,-Wshift-overflow3}, and … >> >> I don't see why we should put a comma after an option reference. > > You explained it yourself later on: > >> It's all related to Texinfo. Sphinx generates e.g. >> Enabled by @ref{7,,-Wall} and something else. >> >> as documented here: >> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040ref.html >> >> Then it ends with the following info output: >> >> Enabled by *note -Wall: 7. and something else. >> >> So the period is added by Texinfo. If I put comma after a reference, then >> the period is not added there. > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > So the purpose of having the comma there is to avoid having a period > in the middle of a sentence, which is added by makeinfo (because the > Info readers need that). Having a comma there may seem a bit > redundant, but having a period will definitely look like a typo, if > not confuse the heck out of the reader, especially if you want to use > these inline cross-references so massively. Well, then it's a bug in Makeinfo. If I want a comma (or a dot), I would have put it these. So emitting 'Enabled by *note -Wall: 7. and something else.' for 'Enabled by @ref{7,,-Wall} and something else.' seems bogus to me. > >>> I don't think the GCC manuals should necessarily be bound by the >>> Sphinx standards. Where those standards are sub-optimal, it is >>> perfectly okay for GCC (and other projects) to deviate. GCC and other >>> GNU manuals used a certain style and convention for decades, so >>> there's more than enough experience and tradition to build on. >> >> What type of conversions and style are going to change with conversion to Sphinx? > > Anything that is different from the style conventions described in the > Texinfo manual. We have many such conventions. Which is supposed to be here: https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation right? I've just the text. About the shortening of section names in a TOC. I couldn't find it in the GNU Documentation manual. > >> Do you see any of them worse than what we have now? > > I didn't bother reading the Sphinx guidelines yet, and don't know when > (and if) I will have time for that. I do think the comparison should > be part of the job or moving to Sphinx. > >>> I will no longer pursue this point, but let me just say that I >>> consider it a mistake to throw away all the experience collected using >>> Texinfo just because Sphinx folks have other traditions and >>> conventions. It might be throwing the baby with the bathwater. >>> >> >> Again, please show up concrete examples. What you describe is very theoretical. > > We've already seen one: the style of writing inline cross-references > with the equivalent of @ref. We also saw another: the way you > converted the menus. It is quite clear to me that there will be > others. So I'm not sure why you need more evidence that this could be > a real issue. As explained, @ref are generated by Makeinfo in a strange way. About the menus, I was unable to find it.. > > But maybe all of this is intentional: maybe the GCC project > consciously and deliberately decided to move away of the GNU > documentation style and conventions, and replace them with whatever > the Sphinx and RST conventions are? In that case, there's no reason > for me to even mention these aspects. My intention is preserving status quo as much as possible. Some constructs are different in Sphinx and some Sphinx improvements (like option references) apparently bring up next challenges to info manuals. On the other hand, Sphinx provides quite some nice features why I wanted to use it. Cheers, Martin