On 6/29/21 6:57 PM, Eli Zaretskii wrote:
From: Martin Liška <mli...@suse.cz>
Date: Tue, 29 Jun 2021 12:09:23 +0200
Cc: GCC Development <g...@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
