On 2/14/19 11:37 PM, David Malcolm wrote: > On Thu, 2019-02-14 at 14:19 -0700, Martin Sebor wrote: >> On 2/13/19 6:48 AM, Martin Liška wrote: >>> Hi. >>> >>> I'm sending patch where I document changes I made during GCC 9 >>> development. I would appreciate both language and factical comments >>> about the patch. >> >> Nothing technical, just a few very minor language nits/suggestions. >> >> Martin >> >> diff --git a/htdocs/gcc-9/changes.html b/htdocs/gcc-9/changes.html >> index 13243c2..9fec9e2 100644 >> --- a/htdocs/gcc-9/changes.html >> +++ b/htdocs/gcc-9/changes.html >> @@ -50,11 +50,64 @@ a work-in-progress.</p> >> <h2 id="general">General Improvements</h2> >> <ul> >> <li> >> - A new option -flive-patching=[inline-only-static|inline-clone] >> is >> + A new option >> <code>-flive-patching=[inline-only-static|inline-clone]</code> is >> >> s/is/has been/ would be better (and either a comma after option or >> a definite article without the comma). >> >> introduced to provide a safe compilation for live-patching. At >> the >> same >> time, provides multiple-level control on the enabled IPA >> optimizations. >> See the user guide for further information about the option for >> more >> - details. >> + details. > > Ideally we should add URLs any time we mention an option, linking to > the docs for that option. texinfo's HTML toolchain does give us per- > option anchors. They're not visible [1], but "View Source" shows us > that they do exist; in the form: > > https://gcc.gnu.org/onlinedocs/gcc/SOMETHING.html#indexOPTION > > though annoyingly the SOMETHING varies depending on what kind of option > it is. > > The pertinent one here is: > https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-flive-patching
Hi. Good idea, I'm attaching patch that does that for all options. There are 2 issues I see: - https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html page is missing links for sub-options - option like -mlra appears multiple times (in each target documenting the option). Before doing the GCC 9.1 release we should adjust URLs in order to point to: https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/... > > (FWIW, I have a patch for GCC 10 that emits terminal sequences to > "linkify" the output when diagnostics mention option names, adding a > URL to the docs for the pertinent option). That sound interesting! Martin > > [...snip...] > > Dave > > [1] I've emailed the texinfo project about this >
>From 48f2df117e3339d44910fdca3136d29369aaeb69 Mon Sep 17 00:00:00 2001 From: marxin <mli...@suse.cz> Date: Fri, 15 Feb 2019 13:38:13 +0100 Subject: [PATCH] Provide URL links for options and built-ins. --- htdocs/gcc-9/changes.html | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/htdocs/gcc-9/changes.html b/htdocs/gcc-9/changes.html index 4d30ed4..fdb668b 100644 --- a/htdocs/gcc-9/changes.html +++ b/htdocs/gcc-9/changes.html @@ -50,7 +50,7 @@ a work-in-progress.</p> <h2 id="general">General Improvements</h2> <ul> <li> - A new option, <code>-flive-patching=[inline-only-static|inline-clone]</code>, has been + A new option, <code><a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-flive-patching";>-flive-patching=[inline-only-static|inline-clone]</code></a>, has been introduced to provide a safe compilation for live-patching. At the same time, provides multiple-level control on the enabled IPA optimizations. See the user guide for more details about the option. @@ -60,13 +60,14 @@ a work-in-progress.</p> option completion in a shell. It is intended to be used by Bash-completion. </li> <li> - The alignment-related options <code>-falign-functions</code>, - <code>-falign-labels</code><code>, </code>-falign-loops - and <code>-falign-jumps</code> received support for a secondary + The alignment-related options <a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-falign-functions";><code>-falign-functions</code></a>, + <a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-falign-labels";><code>-falign-labels</code></a>, + <a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-falign-loops";><code>-falign-loops</code></a>, + and <a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-falign-jumps";><code>-falign-jumps</code></a> received support for a secondary alignment (e.g. <code>-falign-loops=n:m:n2:m2</code>). </li> <li> - A new built-in function, <code>__builtin_expect_with_probability</code>, + A new built-in function, <a href="https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fexpect_005fwith_005fprobability";><code>__builtin_expect_with_probability</code></a>, has been added. </li> <li> @@ -75,7 +76,7 @@ a work-in-progress.</p> </li> <li> A linear function expression defined as ia switch statement with cases - can be transformed by <code>-ftree-switch-conversion</code>. For example: + can be transformed by <a href="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftree-switch-conversion";><code>-ftree-switch-conversion</code></a>. For example: <blockquote><pre class="blackbg"> int foo (int how) @@ -94,15 +95,15 @@ foo (int how) in the switch statement). </li> <li> - The gcov tool received a new option <code>--use-hotness-colors</code> + The gcov tool received a new option <a href="https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov";><code>--use-hotness-colors</code></a> (<code>-q</code>) that can provide perf-like coloring of hot functions. </li> <li> The gcov tool has changed its intermediate format to a new JSON format. </li> <li> - New pair of profiling options (<code>-fprofile-filter-files</code> - and <code>-fprofile-exclude-files</code>) has been added. + New pair of profiling options (<a href="https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html#index-fprofile-filter-files";><code>-fprofile-filter-files</code></a> + and <a href="https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html#index-fprofile-exclude-files";<code>-fprofile-exclude-files</code></a>) has been added. The options help to filter which source files are instrumented. </li> <li> @@ -129,13 +130,13 @@ foo (int how) <li>New extensions: <ul> - <li><code>__builtin_convertvector</code> built-in for vector conversions + <li><a href="https://gcc.gnu.org/onlinedocs/gcc/Vector-Extensions.html#index-_005f_005fbuiltin_005fconvertvector";><code>__builtin_convertvector</code></a> built-in for vector conversions has been added. </li> </ul></li> <li>New warnings: <ul> - <li><code>-Waddress-of-packed-member</code>, enabled by default, + <li><a href="https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Waddress-of-packed-member";<code>-Waddress-of-packed-member</code></a>, enabled by default, warns about an unaligned pointer value from the address of a packed member of a struct or union. </li> @@ -146,13 +147,13 @@ foo (int how) <ul> <li>New warnings: <ul> - <li><code>-Wdeprecated-copy</code>, implied by <code>-Wextra</code>, warns + <li><a href="https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html#index-Wdeprecated-copy";><code>-Wdeprecated-copy</code></a>, implied by <code>-Wextra</code>, warns about the C++11 deprecation of implicitly declared copy constructor and assignment operator if one of them is user-provided. <code>-Wdeprecated-copy-dtor</code> also warns if the destructor is user-provided, as specified in C++11. </li> - <li><code>-Winit-list-lifetime</code>, on by default, warns about uses + <li><a href="https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Dialect-Options.html#index-Winit-list-lifetime";><code>-Winit-list-lifetime</code></a>, on by default, warns about uses of <code>std::initializer_list</code> that are likely to result in a dangling pointer, such as returning or assigning from a temporary list. </li> @@ -235,8 +236,8 @@ foo (int how) module <code>IEEE_ARITHMETIC</code>. </li> <li> - A new command line option <code>-fdec-include</code>, set also - by <code>-fdec</code> option, has been added for an extension + A new command line option <a href="https://gcc.gnu.org/onlinedocs/gfortran/Fortran-Dialect-Options.html#index-fdec-include";><code>-fdec-include</code></a>, set also + by <a href="https://gcc.gnu.org/onlinedocs/gfortran/Fortran-Dialect-Options.html#index-fdec";><code>-fdec</code></a> option, has been added for an extension for compatibility with legacy code. With this option, <code>INCLUDE</code> directive is parsed also as a statement, which allows the directive to be written on multiple source lines @@ -283,7 +284,7 @@ foo (int how) <ul> <li> The AArch64 port now has support for stack clash protection using the - <code>-fstack-clash-protection</code> option. The probing interval/guard + <a href="https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html#index-fstack-protector";><code>-fstack-clash-protection</code></a> option. The probing interval/guard size can be set by using <code>--param stack-clash-protection-guard-size=12|16</code>. The value of this parameter must be in bytes represented as a power of two. The two supported values for this parameter are 12 (for a 4KiB size, 2^12) -- 2.20.1
