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 D38903888807; Thu, 1 Jul 2021 12:44:11 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D38903888807 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 D418D228BE; Thu, 1 Jul 2021 12:44:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625143450; 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=MbgYY208xFxC5MS19r6j5qx5NuTthnfwo6FqA/pN+n0=; b=qRcGM8pRObyaaB6NvvEJWzRraMwgGA9pCCxP4gzjkw6QU0sGuVQUmDN885+OJ/xL8HQhqF xzrt79fp6ZzYnq55PGpk662TTXTVPzzy6HguzfkeBkHRZ2+nsVhrBlm3Eb2NWV48HRCiEf sT9xRnHrDx2sg33LD0EUlueE0XD8QPo= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625143450; 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=MbgYY208xFxC5MS19r6j5qx5NuTthnfwo6FqA/pN+n0=; b=K0bs7rIdf6QOc1FfAOMyOLCZZ/5nyIe+y6qhJuDz5J/BlNQMU+AHJs7xj5hJuEdnjerh1h UAfkDU8RT7XG8tAw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id AFB2F11CC0; Thu, 1 Jul 2021 12:44:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625143450; 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=MbgYY208xFxC5MS19r6j5qx5NuTthnfwo6FqA/pN+n0=; b=qRcGM8pRObyaaB6NvvEJWzRraMwgGA9pCCxP4gzjkw6QU0sGuVQUmDN885+OJ/xL8HQhqF xzrt79fp6ZzYnq55PGpk662TTXTVPzzy6HguzfkeBkHRZ2+nsVhrBlm3Eb2NWV48HRCiEf sT9xRnHrDx2sg33LD0EUlueE0XD8QPo= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625143450; 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=MbgYY208xFxC5MS19r6j5qx5NuTthnfwo6FqA/pN+n0=; b=K0bs7rIdf6QOc1FfAOMyOLCZZ/5nyIe+y6qhJuDz5J/BlNQMU+AHJs7xj5hJuEdnjerh1h UAfkDU8RT7XG8tAw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id HHsGKpq43WCnKwAALh3uQQ (envelope-from ); Thu, 01 Jul 2021 12:44:10 +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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Thu, 1 Jul 2021 14:44:10 +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: <83pmw3mrcg.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, 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 12:44:13 -0000 On 6/30/21 3:09 PM, Eli Zaretskii wrote: >> Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org >> From: Martin Liška >> Date: Wed, 30 Jun 2021 12:11:03 +0200 >> >>> (Admittedly, Emacs by default hides some of the text of a >>> cross-reference, but not hiding them in this case produces an even >>> less legible text.) >> >> If I'm correct, it's exactly what's documented in Sphinx FAQ here: >> https://www.sphinx-doc.org/en/master/faq.html#displaying-links >> >> and there's a suggested Emacs code snippet that should help with links. >> Does it help? > > 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. About ‘=iso9899:1990’, yes, it's a :samp: and how it's wrapper by Sphinx by default. > > The quotes around the option values don't help. > > Also, using the method proposed by Sphinx FAQ would need a change in > Emacs, which will take time to propagate. So my suggestion is to > minimize the use of such "inline" hyperlinks. > >>> ‘@`file'’ >>> >>> Read command-line options from ‘`file'’. The options read are >>> inserted in place of the original ‘@`file'’ option. If ‘`file'’ >>> does not exist, or cannot be read, then the option will be treated >>> literally, and not removed. >> >> I can confirm that, so e.g. >> Show :samp:`Samp with a {variable}.` >> >> is transformed into: >> Show @code{Samp with a @emph{variable}.} >> >> Default info formatting is selected as: >> >> @definfoenclose strong,`,' >> @definfoenclose emph,`,' >> >> 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. > >>> 4. Menus lost the short descriptions of the sub-sections. Example: >>> >>> * Designated Initializers >>> * Case Ranges >>> * Cast to a Union Type >>> * Mixed Declarations, Labels and Code >>> * Declaring Attributes of Functions >>> >>> vs >>> >>> * Designated Inits:: Labeling elements of initializers. >>> * Case Ranges:: 'case 1 ... 9' and such. >>> * Cast to Union:: Casting to union type from any member of the union. >>> * Mixed Declarations:: Mixing declarations and code. >>> * Function Attributes:: Declaring that functions have no side effects, >>> or that they can never return. >>> >>> Looks like some bug to me. >>> >>> 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. Cheers, Martin