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 8508D3855005; Fri, 2 Jul 2021 09:40:08 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8508D3855005 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 703802005F; Fri, 2 Jul 2021 09:40:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625218807; 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=5K7PXmKuPFubykdK5AYpOQdgq9D0RWkKogM1QQSqV1k=; b=abE4MBdJv4cu4srjDvm/6JNOrLijgeTo24abz0eZEKm9bIrtcvsVupRb0UIRvAYs7GfjwN EcehaHinqtjAoonagSWxeK0/G1IXL6EvW5hle6M6cg1DaqAX+nSWA2At7vBMyRpVzoK6TE wte5XEdCcjkKLvLQbLBRUmAyNodYFis= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625218807; 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=5K7PXmKuPFubykdK5AYpOQdgq9D0RWkKogM1QQSqV1k=; b=UX/Rk2f9TpJte5soejHLRetLoDwzL8OCjRNsRh/Ig7DW1iGkLfgd0e77SvLZxbd5l0D3Bh 9jf8kLfUEfv064Bw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 463AC11CD6; Fri, 2 Jul 2021 09:40:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625218807; 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=5K7PXmKuPFubykdK5AYpOQdgq9D0RWkKogM1QQSqV1k=; b=abE4MBdJv4cu4srjDvm/6JNOrLijgeTo24abz0eZEKm9bIrtcvsVupRb0UIRvAYs7GfjwN EcehaHinqtjAoonagSWxeK0/G1IXL6EvW5hle6M6cg1DaqAX+nSWA2At7vBMyRpVzoK6TE wte5XEdCcjkKLvLQbLBRUmAyNodYFis= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625218807; 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=5K7PXmKuPFubykdK5AYpOQdgq9D0RWkKogM1QQSqV1k=; b=UX/Rk2f9TpJte5soejHLRetLoDwzL8OCjRNsRh/Ig7DW1iGkLfgd0e77SvLZxbd5l0D3Bh 9jf8kLfUEfv064Bw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id PNyxD/fe3mDjRgAALh3uQQ (envelope-from ); Fri, 02 Jul 2021 09:40:07 +0000 Subject: Re: [PATCH] Port GCC documentation to Sphinx To: Michael Matz Cc: Eli Zaretskii , gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com 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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Fri, 2 Jul 2021 11:40:06 +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: 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, 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:40:10 -0000 On 7/1/21 5:06 PM, Michael Matz wrote: > Hello, > > On Thu, 1 Jul 2021, Martin Liška wrote: > >> 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. > > Not everyone reads info within Emacs; even if there's an emacs solution to > postprocess info pages to make them nicer we can't rely on that. Sure. What's new is that Sphinx can generate much more cross references, like option references from option listing. > It must > look sensible without that. In this case it seems that already the > generated .texinfo input to makeinfo is bad, where does the 'e' (or 'f') > come from? The original texinfo file simply contains: These are auto-numbered. Theoretically one can use the verbose anchor names: @anchor{demo cmdoption-Wshift-overflow3}@anchor{e}@anchor{demo cmdoption-wshift-overflow3}@anchor{f} @deffn {Option} @w{-}Wshift@w{-}overflow3=n, @w{-}Wshift@w{-}overflow3 Default option value for @ref{e,,-Wshift-overflow3}. But these would lead to even longer '*note -Wshift-overflow3: demo cmdoption-wshift-overflow3' output. > > @option{-std=iso9899:1990} > > so that's what perhaps should be generated, or maybe the anchor in @ref is > optional and could be left out if it doesn't provide any info (a single > character as anchor doesn't seem very useful)? Yes, we can theoretically block emission of @refs for options. Martin > >>>>>> 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. > > Then that needs to be different already in the input, so that the > directive that (in info) capitalizes is only used in contexts where that > makes sense. People reading info pages will know that an all-caps word > often means a syntactic variable/placeholder, so that should be preserved. > > > Ciao, > Michael. >