Re: [PATCH] Port GCC documentation to Sphinx

["Martin Liška" <mliska@suse.cz>]

On 6/29/21 6:57 PM, Eli Zaretskii wrote:
>> 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.

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
>