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

["Arsen Arsenović" <arsen@aarsen.me>]

[-- Attachment #1: Type: text/plain, Size: 2369 bytes --]


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


-- 
Arsen Arsenović

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 381 bytes --]