From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mout-p-103.mailbox.org (mout-p-103.mailbox.org [80.241.56.161]) by sourceware.org (Postfix) with ESMTPS id CCD8B3858C60 for ; Thu, 9 Mar 2023 21:02:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org CCD8B3858C60 Authentication-Results: sourceware.org; dmarc=pass (p=reject dis=none) header.from=aarsen.me Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=aarsen.me Received: from smtp202.mailbox.org (smtp202.mailbox.org [10.196.197.202]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-103.mailbox.org (Postfix) with ESMTPS id 4PXhT51JvRz9scc; Thu, 9 Mar 2023 22:02:17 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=aarsen.me; s=MBO0001; t=1678395737; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=YR5LyY8ff18UCUhyTuQdPu3hU6ZTPgK57iLxZiJG9Jk=; b=dQoJQ6zqPjWVFtjdklIm+CysUWxgNCzdDii7g7nRMZtIPsd51FaT8N/ePfXmnUum6n5xaK nQO+6nOySEE71eXvXg5K2BOnJGHnNJq29T4nul6pcpwfKeh7DOlyCHdVlK3vK4bSe+9MAh NksS37sAW0xRUsOiG8OCMtCr0DWFcXQvGOd8AzvmzTP84z9IdqD5JAKLZkA3N8rWmEgyon QrxwDVzLbjAEKDQvN/UbbCbIy8guo/9jDN4fQOwH/m3mUbNU4FN3fp8xVzvKvvZo+nCZm/ nMli+7dfq3d9SlzwzOBeDAmEUaoFDAviF9YtBgqg9GrcszVI9jnwcUmF4BzHiQ== References: <20230223102714.3606058-1-arsen@aarsen.me> <20230223102714.3606058-2-arsen@aarsen.me> <9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com> From: Arsen =?utf-8?Q?Arsenovi=C4=87?= To: Sandra Loosemore Cc: gcc-patches@gcc.gnu.org, Gerald Pfeifer , Joseph Myers Subject: Re: [PATCH v2 1/5] docs: Create Indices appendix Date: Thu, 09 Mar 2023 21:38:16 +0100 In-reply-to: <9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com> Message-ID: <86sfed63l6.fsf@aarsen.me> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="==-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Status: No, score=-10.7 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,KAM_INFOUSMEBIZ,KAM_SHORT,RCVD_IN_DNSWL_LOW,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --==-=-= Content-Type: multipart/mixed; boundary="=-=-=" --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Sandra Loosemore writes: > On 2/23/23 03:27, Arsen Arsenovi=C4=87 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, th= is > 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: --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-update_web_docs_git-Set-CONTENTS_OUTPUT_LOCATION-inl.patch Content-Transfer-Encoding: quoted-printable Content-Description: [PATCH] update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=inline From=200a0c9469301fb25c4b420a1ed4e381f5ea921d07 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Arsen=3D20Arsenovi=3DC4=3D87?=3D Date: Thu, 9 Mar 2023 21:44:29 +0100 Subject: [PATCH] update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=3Dinline maintainer-scripts/ChangeLog: * update_web_docs_git: Set CONTENTS_OUTPUT_LOCATION=3Dinline in order to put @shortcontents above contents. See 9dd976a4-4e09-d901-b949-6d5037567b9b@codesourcery.com on gcc-patches. =2D-- maintainer-scripts/update_web_docs_git | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintainer-scripts/update_web_docs_git b/maintainer-scripts/up= date_web_docs_git index 9ded1744df4..c9f14d1a4d1 100755 =2D-- 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" =3D "gnat_ugn" ]; then includes=3D"$includes -I gcc/gcc/ada -I gcc/gcc/ada/doc/gnat_ugn" fi =2D makeinfo --html --css-ref $CSS $includes -o ${file} ${filename} + makeinfo --html -c CONTENTS_OUTPUT_LOCATION=3Dinline --css-ref $CSS $i= ncludes -o ${file} ${filename} tar cf ${file}-html.tar ${file}/*.html texi2dvi $includes -o ${file}.dvi ${filename} /dev/null &&= dvips -o ${file}.ps ${file}.dvi texi2pdf $includes -o ${file}.pdf ${filename} 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 m= akes > the [Index] link point at the indices, I think it is OK, although I'm sti= ll > 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 partic= ular, > 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 =2D-=20 Arsen Arsenovi=C4=87 --=-=-=-- --==-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iOYEARYKAI4WIQT+4rPRE/wAoxYtYGFSwpQwHqLEkwUCZApJVV8UgAAAAAAuAChp c3N1ZXItZnByQG5vdGF0aW9ucy5vcGVucGdwLmZpZnRoaG9yc2VtYW4ubmV0RkVF MkIzRDExM0ZDMDBBMzE2MkQ2MDYxNTJDMjk0MzAxRUEyQzQ5MxAcYXJzZW5AYWFy c2VuLm1lAAoJEFLClDAeosST1HQBAPm9SZBmeASBWpL0/KqAKXxu2yL6lhH8t/qg bcCQeTKGAQDg3pK6zfvZfvKocZnB4DGNIaaJ7/KAtCiOouyBtKsxAw== =o6kf -----END PGP SIGNATURE----- --==-=-=--