Re: [PATCH v2 1/5] docs: Create Indices appendix

[Sandra Loosemore <sandra@codesourcery.com>]

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