[v2,1/5] docs: Create Indices appendix
Checks
Commit Message
The GCC manual has multiple indices. By creating an appendix which
lists them, we help makeinfo present a more accessible way for the
reader to see all the indices.
gcc/ChangeLog:
* doc/gcc.texi: Add the Indices appendix, to make texinfo
generate nice indices overview page.
(@copying): Move "This file documents the use of the GNU
compilers" into @copying. Add quotations around cover texts.
---
gcc/doc/gcc.texi | 33 ++++++++++++++++++++++-----------
1 file changed, 22 insertions(+), 11 deletions(-)
Comments
On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote:
> The GCC manual has multiple indices. By creating an appendix which
> lists them, we help makeinfo present a more accessible way for the
> reader to see all the indices.
>
> gcc/ChangeLog:
>
> * doc/gcc.texi: Add the Indices appendix, to make texinfo
> generate nice indices overview page.
> (@copying): Move "This file documents the use of the GNU
> compilers" into @copying. Add quotations around cover texts.
I guess this patch is OK and is necessary to smooth over some misfeatures
in newer versions of Texinfo. In particular, comparing your sample output
https://www.aarsen.me/~arsen/final/gcc.html/index.html
to my own fresh Texinfo 6.7-generated version with your patches applied,
and the existing online documention like
https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/index.html
the order of the "Short Table of Contents" and longer "Table of
Contents" have been switched, so that in the new version you have to
scroll all the way down to the bottom of the page (ugh) to click on
"Option Index". (Frankly, this seems like a misfeature; the point of
having a "Short Table of Contents" is *not* to have to page through the
long one to find a particular chapter.)
I guess that is a Texinfo change? gcc.texi still has:
@summarycontents
@contents
in that order.
OTOH, I see that in your new version there is now a line with links
[Contents][Index] before the Introduction. If adding this new appendix
makes the [Index] link point at the indices, I think it is OK, although
I'm still worried that the overall effect (even without the new version
of Texinfo) is making the indices harder to find.
I wonder, could we add something to the Introduction text like
Tip: This manual is very long. If you're looking for something in
particular, try searching the @ref{Option Index} or @ref{Concept and
Symbol Index}.
???
-Sandra
Sandra Loosemore <sandra@codesourcery.com> writes:
> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote:
>> The GCC manual has multiple indices. By creating an appendix which
>> lists them, we help makeinfo present a more accessible way for the
>> reader to see all the indices.
>> gcc/ChangeLog:
>> * doc/gcc.texi: Add the Indices appendix, to make texinfo
>> generate nice indices overview page.
>> (@copying): Move "This file documents the use of the GNU
>> compilers" into @copying. Add quotations around cover texts.
>
>
> I guess this patch is OK and is necessary to smooth over some misfeatures
> in newer versions of Texinfo. In particular, comparing your sample output
> https://www.aarsen.me/~arsen/final/gcc.html/index.html
>
> to my own fresh Texinfo 6.7-generated version with your patches applied, and
> the existing online documention like
>
> https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/index.html
>
> the order of the "Short Table of Contents" and longer "Table of Contents" have
> been switched, so that in the new version you have to scroll all the way down
> to the bottom of the page (ugh) to click on "Option Index". (Frankly, this
> seems like a misfeature; the point of having a "Short Table of Contents" is
> *not* to have to page through the long one to find a particular chapter.)
>
> I guess that is a Texinfo change? gcc.texi still has:
>
> @summarycontents
> @contents
>
> in that order.
Hm, I hadn't noticed that.. That is odd. I'll figure out why this
happens later today. Thanks for raising this to my attention.
> OTOH, I see that in your new version there is now a line with links
> [Contents][Index] before the Introduction. If adding this new appendix makes
> the [Index] link point at the indices, I think it is OK, although I'm still
> worried that the overall effect (even without the new version of Texinfo) is
> making the indices harder to find.
>
> I wonder, could we add something to the Introduction text like
>
> Tip: This manual is very long. If you're looking for something in particular,
> try searching the @ref{Option Index} or @ref{Concept and Symbol Index}.
>
> ???
I think this is a good idea in either case. It should certainly help
users unaccustomed to Texinfo in locating things quickly.
> -Sandra
Sandra Loosemore <sandra@codesourcery.com> writes:
> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote:
>> The GCC manual has multiple indices. By creating an appendix which
>> lists them, we help makeinfo present a more accessible way for the
>> reader to see all the indices.
>> gcc/ChangeLog:
>> * doc/gcc.texi: Add the Indices appendix, to make texinfo
>> generate nice indices overview page.
>> (@copying): Move "This file documents the use of the GNU
>> compilers" into @copying. Add quotations around cover texts.
>
>
> I guess this patch is OK and is necessary to smooth over some misfeatures
> in newer versions of Texinfo. In particular, comparing your sample output
> https://www.aarsen.me/~arsen/final/gcc.html/index.html
>
> to my own fresh Texinfo 6.7-generated version with your patches applied, and
> the existing online documention like
>
> https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/index.html
>
> the order of the "Short Table of Contents" and longer "Table of Contents" have
> been switched, so that in the new version you have to scroll all the way down
> to the bottom of the page (ugh) to click on "Option Index". (Frankly, this
> seems like a misfeature; the point of having a "Short Table of Contents" is
> *not* to have to page through the long one to find a particular chapter.)
>
> I guess that is a Texinfo change? gcc.texi still has:
>
> @summarycontents
> @contents
>
> in that order.
Found the change. HTML got support for CONTENTS_OUTPUT_LOCATION, which
defaults to after_top, which ignores the inline location of these
elements. Here's a patch:
I pushed the updated docs, and added that commit to my branch (as well
as rebasing it, as always).
> OTOH, I see that in your new version there is now a line with links
> [Contents][Index] before the Introduction. If adding this new appendix makes
> the [Index] link point at the indices, I think it is OK, although I'm still
> worried that the overall effect (even without the new version of Texinfo) is
> making the indices harder to find.
>
> I wonder, could we add something to the Introduction text like
>
> Tip: This manual is very long. If you're looking for something in particular,
> try searching the @ref{Option Index} or @ref{Concept and Symbol Index}.
>
> ???
Even with the above fixed, I think it'd be nice to add this text.
> -Sandra
On 3/9/23 13:38, Arsen Arsenović wrote:
>
> Found the change. HTML got support for CONTENTS_OUTPUT_LOCATION,
> which defaults to after_top, which ignores the inline location of
> these elements. Here's a patch:
>
> maintainer-scripts/ChangeLog:
>
> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
> order to put @shortcontents above contents. See
> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
> gcc-patches.
I don't think this is an adequate fix. We mere mortals build the
manuals with "make html" etc instead of the maintainer scripts for the
web site, so we need a solution that we can put either in the Makefile
or directly in the .texi files, that won't blow up for older versions of
Texinfo that don't support this thing.
-Sandra
Sandra Loosemore <sandra.loosemore@siemens.com> writes:
> On 3/9/23 13:38, Arsen Arsenović wrote:
>> Found the change. HTML got support for CONTENTS_OUTPUT_LOCATION,
>> which defaults to after_top, which ignores the inline location of
>> these elements. Here's a patch:
>> maintainer-scripts/ChangeLog:
>> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
>> order to put @shortcontents above contents. See
>> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
>> gcc-patches.
>
> I don't think this is an adequate fix. We mere mortals build the manuals with
> "make html" etc instead of the maintainer scripts for the web site, so we need
> a solution that we can put either in the Makefile or directly in the .texi
> files, that won't blow up for older versions of Texinfo that don't support this
> thing.
Hm, I've forgotten about that. AFAICT, the only way to specify this
customization variable is through makeinfo flags. It'd seem that
unrecognized variables produce a warning, though, so at least building
with older versions won't fail.
We could probably test for whether -c CONTENTS_OUTPUT_LOCATION produces
no warning, and if so, pass an extra flag in the makefile, or just
accept the warning on older versions (before 6.8).
Those, IIUC, should behave as if CONTENTS_OUTPUT_LOCATION is set to
inline, but I haven't tested that (it's getting quite late).
Also worth noting is that the contents come before the top node when set
up like this. It might be nice to gate that behind @ifhtml or such.
Maybe we should also consider suggesting that texi2any places
@shortcontents first in after_top mode. I can handle that if you think
that's reasonable.
I'll send the updated patch in the morning.
> -Sandra
Thanks, have a lovely night.
Sandra Loosemore <sandra.loosemore@siemens.com> writes:
> On 3/9/23 13:38, Arsen Arsenović wrote:
>> Found the change. HTML got support for CONTENTS_OUTPUT_LOCATION,
>> which defaults to after_top, which ignores the inline location of
>> these elements. Here's a patch:
>> maintainer-scripts/ChangeLog:
>> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
>> order to put @shortcontents above contents. See
>> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
>> gcc-patches.
>
> I don't think this is an adequate fix. We mere mortals build the manuals with
> "make html" etc instead of the maintainer scripts for the web site, so we need
> a solution that we can put either in the Makefile or directly in the .texi
> files, that won't blow up for older versions of Texinfo that don't support this
> thing.
>
> -Sandra
OK, changed up a bit, what do you think of this:
I tested with a fresh build of texinfo 7.0-dev and 6.0.
On Sat, 11 Mar 2023, Arsen Arsenović wrote:
> OK, changed up a bit, what do you think of this:
> maintainer-scripts/ChangeLog:
>
> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
> order to put @shortcontents above contents. See
> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
> gcc-patches.
In the ChangeLog we only describe *what* has change, so the first half of
the first sentence.
The rest then goes in between the first line of the Git commit message
(= the subject of your mail) and the ChangeLog entries.
> --- a/gcc/configure
> +++ b/gcc/configure
We usually don't post diffs for generated files. Not a biggie, I figured I
mention it since it makes reviewing easier and patches shorter, and thus
tends to increase the chance reviewers short on time jump in. :-)
> --- a/maintainer-scripts/update_web_docs_git
> +++ b/maintainer-scripts/update_web_docs_git
> @@ -169,7 +169,7 @@ for file in $MANUALS; do
> if [ "$file" = "gnat_ugn" ]; then
> includes="$includes -I gcc/gcc/ada -I gcc/gcc/ada/doc/gnat_ugn"
> fi
> - makeinfo --html --css-ref $CSS $includes -o ${file} ${filename}
> + makeinfo --html -c CONTENTS_OUTPUT_LOCATION=inline --css-ref $CSS $includes -o ${file} ${filename}
Sandra deferred to me on this one, so explicitly: Ack, thank you. :-)
Note, update_web_docs_git runs once a day, at 0:50 GMT, see
gcc/maintainer-scripts/crontab, and needs to be updated on the gcc.gnu.org
system. I am happy to do that for you, just drop me a note when the commit
is in.
Gerald
On 3/11/23 05:22, Arsen Arsenović wrote:
>
> OK, changed up a bit, what do you think of this:
>
> maintainer-scripts/ChangeLog:
>
> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
> order to put @shortcontents above contents. See
> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
> gcc-patches.
>
> gcc/ChangeLog:
>
> * configure.ac: Add check for the Texinfo 6.8
> CONTENTS_OUTPUT_LOCATION customization variable and set it if
> supported.
> * configure: Regenerate.
> * Makefile.in (MAKEINFO_TOC_INLINE_FLAG): New variable. Set by
> configure.ac to -c CONTENTS_OUTPUT_LOCATION=inline if
> CONTENTS_OUTPUT_LOCATION support is detected, empty otherwise.
> ($(build_htmldir)/%/index.html): Pass MAKEINFO_TOC_INLINE_FLAG.
> See 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
> gcc-patches.
Hmmm, first off, I think somebody other than me needs to approve the
configure and makefile pieces, as well as the maintainer-scripts part.
It looks conceptually right to me, although I would add a comment to new
configure.ac piece like
"Newer versions of Texinfo put the table of contents in the wrong place
by default in HTML output, but provide a command-line option to restore
the desired behavior. Check whether we need to do that."
I don't know whether the maintainer-scripts change needs to be made
conditional too. :-S
BTW, this change probably needs to be backported to all active GCC
branches (10, 11, and 12) too after it's committed to mainline.
-Sandra
Sandra Loosemore <sandra.loosemore@siemens.com> writes:
> On 3/11/23 05:22, Arsen Arsenović wrote:
>> OK, changed up a bit, what do you think of this:
>> maintainer-scripts/ChangeLog:
>> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
>> order to put @shortcontents above contents. See
>> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
>> gcc-patches.
>> gcc/ChangeLog:
>> * configure.ac: Add check for the Texinfo 6.8
>> CONTENTS_OUTPUT_LOCATION customization variable and set it if
>> supported.
>> * configure: Regenerate.
>> * Makefile.in (MAKEINFO_TOC_INLINE_FLAG): New variable. Set by
>> configure.ac to -c CONTENTS_OUTPUT_LOCATION=inline if
>> CONTENTS_OUTPUT_LOCATION support is detected, empty otherwise.
>> ($(build_htmldir)/%/index.html): Pass MAKEINFO_TOC_INLINE_FLAG.
>> See 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
>> gcc-patches.
>
> Hmmm, first off, I think somebody other than me needs to approve the configure
> and makefile pieces, as well as the maintainer-scripts part. It looks
> conceptually right to me, although I would add a comment to new configure.ac
> piece like
>
> "Newer versions of Texinfo put the table of contents in the wrong place by
> default in HTML output, but provide a command-line option to restore the
> desired behavior. Check whether we need to do that."
This sounds good, will drop in. Who can review these?
> I don't know whether the maintainer-scripts change needs to be made conditional
> too. :-S
I don't think so, I was thinking of omitting it for the usual build too
since it's a nonfatal error to pass non-existent customization
variables, but I decided that this would introduce too much noise to the
normal path. This shouldn't emit a warning on the server that runs the
update anyway since, hopefully, we'd be updating it 7.0dev for the other
goodies.
> BTW, this change probably needs to be backported to all active GCC branches
> (10, 11, and 12) too after it's committed to mainline.
I'm not opposed to doing that.
> -Sandra
Gerald Pfeifer <gerald@pfeifer.com> writes:
> On Sat, 11 Mar 2023, Arsen Arsenović wrote:
>> OK, changed up a bit, what do you think of this:
>
>> maintainer-scripts/ChangeLog:
>>
>> * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline in
>> order to put @shortcontents above contents. See
>> 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on
>> gcc-patches.
>
> In the ChangeLog we only describe *what* has change, so the first half of
> the first sentence.
>
> The rest then goes in between the first line of the Git commit message
> (= the subject of your mail) and the ChangeLog entries.
Ah, OK. I decided to put it there, too (and repeat it twice), since the
ChangeLog crafting script doesn't include the commit message for
context. I've dropped that now.
>
>> --- a/gcc/configure
>> +++ b/gcc/configure
>
> We usually don't post diffs for generated files. Not a biggie, I figured I
> mention it since it makes reviewing easier and patches shorter, and thus
> tends to increase the chance reviewers short on time jump in. :-)
Ah, d'oh. I forgot to filter that out. Apologies.
>
>> --- a/maintainer-scripts/update_web_docs_git
>> +++ b/maintainer-scripts/update_web_docs_git
>> @@ -169,7 +169,7 @@ for file in $MANUALS; do
>> if [ "$file" = "gnat_ugn" ]; then
>> includes="$includes -I gcc/gcc/ada -I gcc/gcc/ada/doc/gnat_ugn"
>> fi
>> - makeinfo --html --css-ref $CSS $includes -o ${file} ${filename}
>> + makeinfo --html -c CONTENTS_OUTPUT_LOCATION=inline --css-ref $CSS $includes -o ${file} ${filename}
>
> Sandra deferred to me on this one, so explicitly: Ack, thank you. :-)
>
> Note, update_web_docs_git runs once a day, at 0:50 GMT, see
> gcc/maintainer-scripts/crontab, and needs to be updated on the gcc.gnu.org
> system. I am happy to do that for you, just drop me a note when the commit
> is in.
Sure thing, thanks!
> Gerald
On Sat, 11 Mar 2023, Arsen Arsenović wrote:
> Sandra Loosemore <sandra.loosemore@siemens.com> writes:
>> Hmmm, first off, I think somebody other than me needs to approve the
>> configure and makefile pieces, as well as the maintainer-scripts part.
>> It looks conceptually right to me
Per gcc/MAINTAINERS that'd be
build machinery (*.in) Paolo Bonzini <bonzini@gnu.org>
build machinery (*.in) Nathanael Nerode <neroden@gcc.gnu.org>
build machinery (*.in) Alexandre Oliva <aoliva@gcc.gnu.org>
build machinery (*.in) Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
though I don't recall seeing much (if anything) from others than Alexandre
for quite a while.
So more likely one of the Global Reviewers in that same file.
Gerald
Gerald Pfeifer <gerald@pfeifer.com> writes:
> On Sat, 11 Mar 2023, Arsen Arsenović wrote:
>> Sandra Loosemore <sandra.loosemore@siemens.com> writes:
>>> Hmmm, first off, I think somebody other than me needs to approve the
>>> configure and makefile pieces, as well as the maintainer-scripts part.
>>> It looks conceptually right to me
>
> Per gcc/MAINTAINERS that'd be
>
> build machinery (*.in) Paolo Bonzini <bonzini@gnu.org>
> build machinery (*.in) Nathanael Nerode <neroden@gcc.gnu.org>
> build machinery (*.in) Alexandre Oliva <aoliva@gcc.gnu.org>
> build machinery (*.in) Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
>
> though I don't recall seeing much (if anything) from others than Alexandre
> for quite a while.
>
> So more likely one of the Global Reviewers in that same file.
Okay, thanks. I'll let some time pass before pinging people for the
v2 I sent yesterday.
With that, we should be left with just a review of the updated Git log
before this series is ready for trunk, IIRC.
Have a great day!
> Gerald
@@ -40,6 +40,9 @@
@c %**end of header
@copying
+This file documents the use of the GNU compilers.
+
+@quotation
Copyright @copyright{} 1988-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@@ -59,6 +62,7 @@ Texts being (a) (see below), and with the Back-Cover Texts being (b)
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.
+@end quotation
@end copying
@ifnottex
@dircategory Software development
@@ -71,7 +75,6 @@ Texts being (a) (see below), and with the Back-Cover Texts being (b)
* lto-dump: (gcc) lto-dump. @command{lto-dump}---Tool for
dumping LTO object files.
@end direntry
-This file documents the use of the GNU compilers.
@sp 1
@insertcopying
@sp 1
@@ -159,8 +162,7 @@ object files.
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors:: People who have contributed to GCC.
-* Option Index:: Index to command line options.
-* Keyword Index:: Index of concepts and symbol names.
+* Indices:: List of indices in this manual.
@end menu
@include frontends.texi
@@ -196,19 +198,28 @@ object files.
@c Indexes
@c ---------------------------------------------------------------------
+@node Indices
+@appendix Indices
+
+@menu
+* Option Index:: Index to command line options.
+* Concept and Symbol Index:: Index of concepts and symbols names.
+@end menu
+
@node Option Index
-@unnumbered Option Index
+@appendixsec Option Index
-GCC's command line options are indexed here without any initial @samp{-}
-or @samp{--}. Where an option has both positive and negative forms
-(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
-relevant entries in the manual are indexed under the most appropriate
-form; it may sometimes be useful to look up both forms.
+GCC's command line options are indexed here without any initial
+@samp{-} or @samp{--}. Where an option has both positive and negative
+forms (such as @option{-f@var{option}} and
+@option{-fno-@var{option}}), relevant entries in the manual are
+indexed under the most appropriate form; it may sometimes be useful to
+look up both forms.
@printindex op
-@node Keyword Index
-@unnumbered Keyword Index
+@node Concept and Symbol Index
+@appendixsec Concept and Symbol Index
@printindex cp