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 D7B4C3855028; Thu, 1 Jul 2021 14:14:31 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D7B4C3855028 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 CECA3204FD; Thu, 1 Jul 2021 14:14:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625148870; 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=ScT8QCHoH9Kl3kfabOe/l8mbCi62pV4vmVPeiIcycDw=; b=zZ7UE2shaNbBVbUxuBCrrC0oYzCQTDxAHjXWTfqnxfYxxSt+H+LSEszB2qOjy42xB/XeLd 2Pe2fHCyC0b+Ktjveog2BlrTUf7NdYQGZ2sehaYwog9eVE1Pm90opAQXU9NiV0+ooZPzqi /cLBORWDeG+LgnrRxK7PfVM75N1Hexs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625148870; 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=ScT8QCHoH9Kl3kfabOe/l8mbCi62pV4vmVPeiIcycDw=; b=7BLOqLsw5Brqjx3lYJbc1dEi4rCa6hklpBqX5u0c9iMpXH/OWU1HnSTOvYvdZYvSOQRos+ h9qknrTwqx7VLaCw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id AAF1311CC0; Thu, 1 Jul 2021 14:14:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625148870; 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=ScT8QCHoH9Kl3kfabOe/l8mbCi62pV4vmVPeiIcycDw=; b=zZ7UE2shaNbBVbUxuBCrrC0oYzCQTDxAHjXWTfqnxfYxxSt+H+LSEszB2qOjy42xB/XeLd 2Pe2fHCyC0b+Ktjveog2BlrTUf7NdYQGZ2sehaYwog9eVE1Pm90opAQXU9NiV0+ooZPzqi /cLBORWDeG+LgnrRxK7PfVM75N1Hexs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625148870; 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=ScT8QCHoH9Kl3kfabOe/l8mbCi62pV4vmVPeiIcycDw=; b=7BLOqLsw5Brqjx3lYJbc1dEi4rCa6hklpBqX5u0c9iMpXH/OWU1HnSTOvYvdZYvSOQRos+ h9qknrTwqx7VLaCw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id d4/jKMbN3WBcYgAALh3uQQ (envelope-from ); Thu, 01 Jul 2021 14:14:30 +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> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> <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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <56699e91-9e02-102e-4277-af8823cf3145@suse.cz> Date: Thu, 1 Jul 2021 16:14:30 +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: <83k0makvk7.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.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, 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 14:14:33 -0000 On 7/1/21 3:33 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 14:44:10 +0200 >> >>> It helps some, but not all of the issues disappear. For example, >>> stuff like this is still hard to read: >>> >>> To select this standard in GCC, use one of the options -ansi >>> ----- >>> -std.‘=c90’ or -std.‘=iso9899:1990’ >>> ---- ---- >> >> 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. > >> About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by default. > > Why is it a separate :samp:? IMO, the correct markup is to make the > entire string -std=iso9899:1990 have the same typeface. In Texinfo, > I'd use > > @option{-std=iso9899:1990} > >>>> We can adjust 'emph' formatting to nil, what do you think? >>> >>> Something like that, yes. But the problem is: how will you format it >>> instead? The known alternatives, _foo_ and *foo* both use punctuation >>> characters, which will get in the way similarly to the quotes. Can >>> you format those in caps, like makeinfo does? >> >> You are fully right, info is very simple format and it uses wrapping for the formatting >> purpose (by default * and _). So, I don't have any elegant solution. > > Well, it sounds from another mail that you did find a solution: to > up-case the string in @var. I don't know. Some of them can be e.g. keywords and using upper-case does not seem to me feasible. > >>>>> Note also that nodes are now called by the same name as the section, >>>>> which means node names generally got much longer. Is that really a >>>>> good idea? >>>> >>>> Well, I intentionally removed these and used simple TOC tree links >>>> which take display text for a section title. >>> >>> I would suggest to discuss these decisions first, perhaps on the >>> Texinfo mailing list? I'm accustomed to these short descriptions, but >>> I'm not sure how important they are for others. >> >> Well, it was decision done during the transition of texinfo files into Sphinx. >> I don't see why it should be discussed in Texinfo community. > > 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. > > 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/ Martin