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 D8673384783A; Fri, 2 Jul 2021 13:23:15 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D8673384783A 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 B652020569; Fri, 2 Jul 2021 13:23:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625232194; 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=QVZ15vAMt6VrTXkGe4a4kB/JM1a8wGPxbcmW1zueaYo=; b=wQv3PFH210E551w8GCeQhANjahKtW3xeb3dWFNVXeh+YvDWhOBAUuNF7c9AO8KxGdEpRTr qFIjFOnTAoI9D+i9UPFhfanFeHtcKGgAT30tN0stItkteE+nVKzE02Ly0wotvRbRiM/XW/ 8Dmvt83HOKJ4OoT2Qo37uVON4HtLpZs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625232194; 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=QVZ15vAMt6VrTXkGe4a4kB/JM1a8wGPxbcmW1zueaYo=; b=H2PicpWVIe41mEFZSqrSgGARtv/fk1e1cunZzRLDz036H2Wp6eOdYLRlSNfcK2hbiNsGPW Q5RH4ptgpllSPoAQ== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 8BE9611C84; Fri, 2 Jul 2021 13:23:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625232194; 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=QVZ15vAMt6VrTXkGe4a4kB/JM1a8wGPxbcmW1zueaYo=; b=wQv3PFH210E551w8GCeQhANjahKtW3xeb3dWFNVXeh+YvDWhOBAUuNF7c9AO8KxGdEpRTr qFIjFOnTAoI9D+i9UPFhfanFeHtcKGgAT30tN0stItkteE+nVKzE02Ly0wotvRbRiM/XW/ 8Dmvt83HOKJ4OoT2Qo37uVON4HtLpZs= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625232194; 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=QVZ15vAMt6VrTXkGe4a4kB/JM1a8wGPxbcmW1zueaYo=; b=H2PicpWVIe41mEFZSqrSgGARtv/fk1e1cunZzRLDz036H2Wp6eOdYLRlSNfcK2hbiNsGPW Q5RH4ptgpllSPoAQ== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id JH8yIUIT32DNPwAALh3uQQ (envelope-from ); Fri, 02 Jul 2021 13:23:14 +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> <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> <83im1tj9ci.fsf@gnu.org> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Fri, 2 Jul 2021 15:23:14 +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: <83im1tj9ci.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 13:23:19 -0000 On 7/2/21 12:31 PM, Eli Zaretskii wrote: >> Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org >> From: Martin Liška >> Date: Fri, 2 Jul 2021 11:30:02 +0200 >> >>> 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. > > No, it isn't a bug in makeinfo. It's a (mis)feature of the Info > format: a cross-reference needs to have a punctuation character after > it, so that Info readers would know where's the end of the node/anchor > name to which the cross-reference points. Info files are largely > plain-ASCII files, so the Info readers need help in this case, and > makeinfo produces what they need. Indeed. Agree that Info format is legacy format with very limited capability of a formatting. > >>>> 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. > > No, there's also a lot of style guidelines in the Texinfo manual > itself. Basically, the documentation of almost every Texinfo > directive includes some style guidelines, and there are also sections > which are pure guidelines, like the nodes "Conventions", "Node Names", > "Structuring Command Types", and some others. You are right, it's mentioned in "Node Names". Anyway, I declare it as a minor regression to the current format. > >>>> 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.. > > See the node "Menu Parts" in the Texinfo manual. If you look at other > GNU manuals, you will see that it is a de-facto standard to provide > most menu items with short descriptions. > >>> 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. > > Well, but you definitely deviated from the status quo, and it sounds > like you did that deliberately, without any discussion. > >> On the other hand, Sphinx provides quite some nice features why I wanted to use it. > > Which features are those? > Feel free to read this email discussion, it's mentioned there multiple times what are main benefits of the transition. Cheers, Martin