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 E83B1383603D; Wed, 30 Jun 2021 10:11:04 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org E83B1383603D 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 A3BF0224FE; Wed, 30 Jun 2021 10:11:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625047863; 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=XQc9x66WeP7dOlY7CXJE0UsiEMFFBpJr6xqBbchSjaU=; b=KAClRdkiY6gOfO0eh6hOPEQzp3l+nVI7dupNVHNxQ1YlJ1pUtgdVpp/njyqKgkgxcCkgCI 4rAj2c+LbC91byVYoiv6FqBsoeWmtsrlrwqkPcdm3ipfVCIH0zoe360MWxQyuZ6MkDtYLu LbTIQATlIG94jbqHAYkHaqTtWTfuE4o= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625047863; 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=XQc9x66WeP7dOlY7CXJE0UsiEMFFBpJr6xqBbchSjaU=; b=Lg2BLS3KGLzTqn8MxVelOR13qQxDvIGHAhk3CkCLzUxgNIxnpjb+oEc+n0+uKsgt0rDPYx y25SLb2+vrFxUXCw== Received: from imap3-int (imap-alt.suse-dmz.suse.de [192.168.254.47]) by imap.suse.de (Postfix) with ESMTP id 7B6C211906; Wed, 30 Jun 2021 10:11:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1625047863; 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=XQc9x66WeP7dOlY7CXJE0UsiEMFFBpJr6xqBbchSjaU=; b=KAClRdkiY6gOfO0eh6hOPEQzp3l+nVI7dupNVHNxQ1YlJ1pUtgdVpp/njyqKgkgxcCkgCI 4rAj2c+LbC91byVYoiv6FqBsoeWmtsrlrwqkPcdm3ipfVCIH0zoe360MWxQyuZ6MkDtYLu LbTIQATlIG94jbqHAYkHaqTtWTfuE4o= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1625047863; 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=XQc9x66WeP7dOlY7CXJE0UsiEMFFBpJr6xqBbchSjaU=; b=Lg2BLS3KGLzTqn8MxVelOR13qQxDvIGHAhk3CkCLzUxgNIxnpjb+oEc+n0+uKsgt0rDPYx y25SLb2+vrFxUXCw== Received: from director2.suse.de ([192.168.254.72]) by imap3-int with ESMTPSA id pDoXHTdD3GDDfgAALh3uQQ (envelope-from ); Wed, 30 Jun 2021 10:11:03 +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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> Date: Wed, 30 Jun 2021 12:11:03 +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: <83a6n8obh4.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.2 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 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 10:11:08 -0000 On 6/29/21 6:57 PM, Eli Zaretskii wrote: >> From: Martin Liška >> Date: Tue, 29 Jun 2021 12:09:23 +0200 >> Cc: GCC Development , gcc-patches@gcc.gnu.org >> >> On 6/28/21 5:33 PM, Joseph Myers wrote: >>> Are formatted manuals (HTML, PDF, man, info) corresponding to this patch >>> version also available for review? >> >> I've just uploaded them here: >> https://splichal.eu/gccsphinx-final/ > > Thanks. Hey! > > I'm an Info junkie, so I grabbed gcc.info from there and skimmed > through it. Please allow me a few unsolicited comments: I really welcome them! > > 1. It sounds like Sphinx is heavily biased towards HTML format, and as > result uglifies the Info format? Hopefully not :) > > For example, many cross-references (AFAIU introduced as part of > migration to Sphinx) make the text illegible in Emacs. Example: > > This standard, in both its forms, is commonly known as `C89', or > occasionally as `C90', from the dates of ratification. To select this > standard in GCC, use one of the options *note -ansi *note -std > .‘=c90’ or *note -std.‘=iso9899:1990’; to obtain all the diagnostics > required by the standard, you should also specify *note -pedantic. > (or *note -pedantic-errors. if you want them to be errors rather > than warnings). See *note Options Controlling C Dialect. > [...] > An amendment to the 1990 standard was published in 1995. This amendment > added digraphs and ‘__STDC_VERSION__’ to the language, but otherwise > concerned the library. This amendment is commonly known as `AMD1'; the > amended standard is sometimes known as `C94' or `C95'. To select this > standard in GCC, use the option *note -std.‘=iso9899:199409’ (with, > as for other standard versions, *note -pedantic. to receive all > required diagnostics). > > Or how about this: > > `Overall Options' > > See Options Controlling the Kind of Output. > > *note -c. *note -S. *note -E. *note -o. ‘`file'’ > *note -dumpbase. ‘`dumpbase'’ *note -dumpbase-ext. > ‘`auxdropsuf'’ *note -dumpdir. ‘`dumppfx'’ ‘-x’ ‘`language'’ > *note -v. *note -###. *note –help.‘[=`class'[,...]]’ > *note –target-help. *note –version. *note -pass-exit-codes > . *note -pipe. *note -specs.‘=`file'’ *note -wrapper > .‘@`file'’ *note -ffile-prefix-map.‘=`old'=`new'’ *note > -fplugin.‘=`file'’ ‘-fplugin-arg-’‘`name'=`arg'’ > ‘-fdump-ada-spec’‘[-`slim']’ *note -fada-spec-parent.‘=`unit'’ > *note -fdump-go-spec.‘=`file'’ > > In the first line, the emphasis became quotes, which sounds sub-optimal. > In the second line, the hyperlink was lost. > And the rest is not really readable. > > Compare this with the original: > > _Overall Options_ > *Note Options Controlling the Kind of Output. > -c -S -E -o FILE -x LANGUAGE > -v -### --help[=CLASS[,...]] --target-help --version > -pass-exit-codes -pipe -specs=FILE -wrapper > @FILE -ffile-prefix-map=OLD=NEW > -fplugin=FILE -fplugin-arg-NAME=ARG > -fdump-ada-spec[-slim] -fada-spec-parent=UNIT -fdump-go-spec=FILE > > (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? > > In general, it is a well-known rule that Texinfo documentation should > NOT use @ref{foo} as if @ref will disappear without a trace, leaving > just the hyperlink to 'foo'. Looks like the rewritten manual uses > that a lot. > > This "see" consistently gets in the way throughout the entire manual. > A few more examples: > > -- Option: -flocal-ivars > > Default option value for *note -fno-local-ivars. > ... > For example *note -std.‘=gnu90 -Wpedantic’ warns about C++ style > ‘//’ comments, while *note -std.‘=gnu99 -Wpedantic’ does not. > ... > If this option is not provided but *note -Wabi.‘=`n'’ is, that > version is used for compatibility aliases. > ... > Below *note -std.‘=c++20’, *note -fconcepts. enables > support for the C++ Extensions for Concepts Technical > Specification, ISO 19217 (2015). > ... > gcov [ *note -v. | *note –version. ] [ ‘-h’ | *note –help. ] > > > 2. The translation of @var produces double-quoting in Info, here's an > example: > > The usual way to run GCC is to run the executable called ‘gcc’, or > ‘`machine'-gcc’ when cross-compiling, or ‘`machine'-gcc-`version'’ to > run a specific version of GCC. > > vs, the old > > The usual way to run GCC is to run the executable called 'gcc', or > 'MACHINE-gcc' when cross-compiling, or 'MACHINE-gcc-VERSION' to run a > specific version of GCC. > > I think the new variant is less readable and more confusing, because > it isn't clear whether the quotes are part of the text. Here's an > extreme example: > > ‘@`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? > > 3. Some cross-references lost the hyperlinks: > > See option-index, for an index to GCC’s options. > > ("option-index" was a hyperlink to the corresponding index section). That's removed in latest version. > > 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. > > 5. There's some strange bug with symbols inside parentheses. For > example: > > In GNU C and C++, you can use function attributes to specify certain > function properties that may help the compiler optimize calls or check > code more carefully for correctness. For example, you can use > attributes to specify that a function never returns ( ‘noreturn’ ), > returns a value depending only on the values of its arguments ( ‘const’ > ), or has ‘printf’ -style arguments ( ‘format’ ). > > See the extra blanks inside parens? The old format was nicer: > > In GNU C and C++, you can use function attributes to specify certain > function properties that may help the compiler optimize calls or check > code more carefully for correctness. For example, you can use > attributes to specify that a function never returns ('noreturn'), > returns a value depending only on the values of its arguments ('const'), > or has 'printf'-style arguments ('format'). > > 6. Something's wrong with the second footnote below: > > ---------- Footnotes ---------- > > (1) > https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt > > (2) (1) A ‘call-used’ register is a register whose contents can be > changed by a function call; therefore, a caller cannot assume that the > register has the same contents on return from the function as it had > before calling the function. Such registers are also called > ‘call-clobbered’, ‘caller-saved’, or ‘volatile’. > > Why does the 2nd footnote have 2 note numbers? I can confirm the following code snippet: Note1: ([#]_) Note2: ([#]_) .. [#] Future versions of GCC may zero-extend, or use a target-defined ``ptr_extend`` pattern. Do not rely on sign extension. .. [#] I am note 2. emits the following texinfo: Note1: (@footnote{@w{(1)} Future versions of GCC may zero-extend, or use a target-defined @code{ptr_extend} pattern. Do not rely on sign extension. }) Note2: (@footnote{@w{(2)} I am note 2. }) Seems correct to be, but it's likely not. Let me investigate that. > > 7. Lines that shouldn't be broken, are: > > ‘`type' __sync_fetch_and_add (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_sub (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_or (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_and (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_xor (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_nand (`type' *ptr, `type' value, ...)’ > > vs > > 'TYPE __sync_fetch_and_add (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_sub (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_or (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_and (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_xor (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_nand (TYPE *ptr, TYPE value, ...)' Yes, I can confirm that, it's on my TODO list right now. Thanks for useful comments. Martin > > HTH >