From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.220.28]) by sourceware.org (Postfix) with ESMTPS id 25B283857419; Thu, 1 Jul 2021 16:04:26 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 25B283857419 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-out1.suse.de (Postfix) with ESMTPS id 2338721E06; Thu, 1 Jul 2021 16:04:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625155465; 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=ynAHEopsJMRAcEOdDo7IB3kHzNlgFH5ODJcgJUiGUsM=; b=oUHhlpqnpHTVVfGO7k0lf1JI1HAFp6nrlR5ZtogSrPu9zTpREJSS5Q+1ZVqqKsZF1+XHW0 zVvUohY5SoOisKxcQYwZVpVpoGO9yTc5iDecjQOedFV/eCzNdagMksSCVdDpXNOupXhJHY m/8UhDgkSt8J63fMKY3ZsUR2lbSTs7s= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625155465; 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=ynAHEopsJMRAcEOdDo7IB3kHzNlgFH5ODJcgJUiGUsM=; b=uWcej/6ZWq9WVrFx39/WH6wmB4PD3LGT1oQZVgD5reLdMN80rJs5hqiwnKLmpVzKwXIyeo krbmAYBUVH2vDoCQ== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id F19EC11CD6; Thu, 1 Jul 2021 16:04:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625155465; 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=ynAHEopsJMRAcEOdDo7IB3kHzNlgFH5ODJcgJUiGUsM=; b=oUHhlpqnpHTVVfGO7k0lf1JI1HAFp6nrlR5ZtogSrPu9zTpREJSS5Q+1ZVqqKsZF1+XHW0 zVvUohY5SoOisKxcQYwZVpVpoGO9yTc5iDecjQOedFV/eCzNdagMksSCVdDpXNOupXhJHY m/8UhDgkSt8J63fMKY3ZsUR2lbSTs7s= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625155465; 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=ynAHEopsJMRAcEOdDo7IB3kHzNlgFH5ODJcgJUiGUsM=; b=uWcej/6ZWq9WVrFx39/WH6wmB4PD3LGT1oQZVgD5reLdMN80rJs5hqiwnKLmpVzKwXIyeo krbmAYBUVH2vDoCQ== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id 6JASOojn3WBeIgAALh3uQQ (envelope-from ); Thu, 01 Jul 2021 16:04:24 +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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <79939338-7f4f-121c-5fa9-316ae0fc47aa@suse.cz> Date: Thu, 1 Jul 2021 18:04:24 +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: <83h7hekpi9.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.3 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: Thu, 01 Jul 2021 16:04:27 -0000 On 7/1/21 5:44 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 16:14:30 +0200 >> >>>> If I understand the notes correct, the '.' should be also hidden by e.g. Emacs. >>> >>> No, it doesn't. The actual text in the Info file is: >>> >>> *note -std: f.‘=iso9899:1990’ >>> >>> and the period after " f" isn't hidden. Where does that "f" come from >>> and what is its purpose here? can it be removed (together with the >>> period)? >> >> It's name of the anchor used for the @ref. The names are automatically generated >> by makeinfo. So there's an example: >> >> This is the warning level of @ref{e,,-Wshift-overflow3} and … >> >> becomes in info: >> This is the warning level of *note -Wshift-overflow3: e. and … >> >> I can ask the question at Sphinx, the Emacs script should hide that. > > 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. > > Does Sphinx somehow generate the period if there's no comma, or does > it do it unconditionally, i.e. even if there is a punctuation after > the closing brace? 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. > >>> This actually raises a more general issue with this Sphinx porting >>> initiative: what will be the canonical style guide for maintaining the >>> GCC manual in Sphinx, or more generally for writing GNU manuals in >>> Sphinx? For Texinfo, we have the Texinfo manual, which both documents >>> the language and provides style guidelines for how to use Texinfo for >>> producing good manuals. Contributors to GNU manuals are using those >>> guidelines for many years. Is there, or will there be, an equivalent >>> style guide for Sphinx? If not, how will the future contributors to >>> the GCC manuals know what are the writing and style conventions? >> >> No, I'm not planning any extra style guide. We will you standard Sphinx RST >> manual and one can find many tutorials about how to do it. > > Are you sure everything there is good for our manuals? Did you > compare the style conventions there with what we have in the Texinfo > manual? I'm not sure, but I made the conversion from Texinfo as close as possible to RST files. I see the documentation markup natural and it matches with we write documentation in Texinfo. > > Moreover, this means people who contribute to other manuals will now > have to learn two different styles, no? And that's in addition to > learning one more language. Yes, people will have to learn RST. Similarly to git conversion, people also had to learn another version control system (we used svn). > >>> That is why I recommended to discuss this on the Texinfo list: that's >>> the place where such guidelines are discussed, and where we have >>> experts who understand the effects and consequences of using this or >>> that style. The current style in GNU manuals is to have the menus as >>> we see them in the existing GCC manuals: with a short description. >>> Maybe there are good reasons to deviate from that style, but >>> shouldn't this be at least presented and discussed, before the >>> decision is made? GCC developers are not the only ones who will be >>> reading the future GCC manuals. >>> >> >> That seems to me a subtle adjustment and it's standard way how people generate >> TOC in Sphinx. See e.g. the Linux kernel documentation: >> https://www.kernel.org/doc/html/latest/ > > 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? Do you see any of them worse than what we have now? > > 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. Thanks, Martin