From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from fencepost.gnu.org (fencepost.gnu.org [IPv6:2001:470:142:3::e]) by sourceware.org (Postfix) with ESMTPS id 495B23835434; Wed, 30 Jun 2021 13:09:34 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 495B23835434 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2334 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lyZy9-00027a-M7; Wed, 30 Jun 2021 09:09:33 -0400 Date: Wed, 30 Jun 2021 16:09:35 +0300 Message-Id: <83pmw3mrcg.fsf@gnu.org> From: Eli Zaretskii To: Martin =?utf-8?Q?Li=C5=A1ka?= Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org In-Reply-To: <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> (message from Martin =?utf-8?Q?Li=C5=A1ka?= on Wed, 30 Jun 2021 12:11:03 +0200) Subject: Re: [PATCH] Port GCC documentation to Sphinx 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> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=2.5 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Level: ** X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) 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: Wed, 30 Jun 2021 13:09:38 -0000 > 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’ ---- ---- 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? > > 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.