Re: [PATCH] Port GCC documentation to Sphinx

[Eli Zaretskii <eliz@gnu.org>]

> From: Martin Liška <mliska@suse.cz>
> Date: Tue, 29 Jun 2021 12:09:23 +0200
> Cc: GCC Development <gcc@gcc.gnu.org>, 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