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 7F99D3885C0A; Thu, 1 Jul 2021 15:06:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 7F99D3885C0A Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.de Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.de Received: from relay2.suse.de (relay2.suse.de [149.44.160.134]) by smtp-out2.suse.de (Postfix) with ESMTP id 741EA1FFBF; Thu, 1 Jul 2021 15:06:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1625151973; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=sEGj/1jY0Jf2c/w38bcXXdK7y8xCVj7WTvV6PMfa3SE=; b=l4YoAyXZJVm89n1e6gNGLnXXnJbhgtAYmPdSm7klZmIHbL36IDyZayG2pFNpR6KVWQSj22 X7ds8UPd8NpmvAutlePkH6bEPzfZH0tTGKzz8vZfgDVuarcALh+tAoTm3QEoD73YKqWN32 D+q9jhPCvNKr6LebdjWfwIyriNp4ciE= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1625151973; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=sEGj/1jY0Jf2c/w38bcXXdK7y8xCVj7WTvV6PMfa3SE=; b=b9YHyTUQ1QqmqHmbafn/wujiWJUmyCEAnmhz4omo6m6NrDYTPj28Zt+6iBdy4g3/RdM/4G hBZHfjVDLhZxXEBw== Received: from wotan.suse.de (wotan.suse.de [10.160.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by relay2.suse.de (Postfix) with ESMTPS id 3F648A3B8A; Thu, 1 Jul 2021 15:06:13 +0000 (UTC) Received: by wotan.suse.de (Postfix, from userid 10510) id 10D45672D; Thu, 1 Jul 2021 15:06:13 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by wotan.suse.de (Postfix) with ESMTP id 0F2B7672C; Thu, 1 Jul 2021 15:06:13 +0000 (UTC) Date: Thu, 1 Jul 2021 15:06:13 +0000 (UTC) From: Michael Matz To: =?ISO-8859-15?Q?Martin_Li=A8ka?= cc: Eli Zaretskii , gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com Subject: Re: [PATCH] Port GCC documentation to Sphinx In-Reply-To: <56699e91-9e02-102e-4277-af8823cf3145@suse.cz> Message-ID: 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> User-Agent: Alpine 2.20 (LSU 67 2015-01-07) MIME-Version: 1.0 X-Spam-Status: No, score=-3.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, 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 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8BIT X-Content-Filtered-By: Mailman/MimeDel 2.1.29 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 15:06:16 -0000 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. 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: @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)? > > > > > 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.