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 4B8C03858C27; Tue, 29 Jun 2021 16:57:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4B8C03858C27 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3524 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 1lyH2u-0004Ua-7A; Tue, 29 Jun 2021 12:57:12 -0400 Date: Tue, 29 Jun 2021 19:57:11 +0300 Message-Id: <83a6n8obh4.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: <2f60f602-5d88-7674-9620-2172748664c5@suse.cz> (message from Martin =?utf-8?Q?Li=C5=A1ka?= on Tue, 29 Jun 2021 12:09:23 +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> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=2.8 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, KAM_EU, 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-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Jun 2021 16:57:15 -0000 > 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. I'm an Info junkie, so I grabbed gcc.info from there and skimmed through it. Please allow me a few unsolicited comments: 1. It sounds like Sphinx is heavily biased towards HTML format, and as result uglifies the Info format? 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.) 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. 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). 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? 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? 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, ...)' HTH