From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gcc-refused-email@gnu.org>
Received: from fencepost.gnu.org (fencepost.gnu.org [IPv6:2001:470:142:3::e])
 by sourceware.org (Postfix) with ESMTPS id 334F9397EC2F;
 Fri,  2 Jul 2021 10:32:29 +0000 (GMT)
DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 334F9397EC2F
Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3206
 helo=home-c4e4a596f7)
 by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@gnu.org>)
 id 1lzGTE-0000zk-Hs; Fri, 02 Jul 2021 06:32:28 -0400
Date: Fri, 02 Jul 2021 13:32:27 +0300
Message-Id: <83h7hdj9ac.fsf@gnu.org>
From: Eli Zaretskii <eliz@gnu.org>
To: Martin =?utf-8?Q?Li=C5=A1ka?= <mliska@suse.cz>
Cc: matz@suse.de, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org,
 joseph@codesourcery.com
In-Reply-To: <f26e353f-b88c-0c3c-d989-73aee2f2997b@suse.cz> (message from
 Martin =?utf-8?Q?Li=C5=A1ka?= on Fri, 2 Jul 2021 11:40:06 +0200)
Subject: Re: [PATCH] Port GCC documentation to Sphinx
References: <1446990946.2994.192.camel@surprise>
 <alpine.DEB.2.22.394.2106021645550.693958@digraph.polyomino.org.uk>
 <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz>
 <alpine.DEB.2.22.394.2106101645050.424830@digraph.polyomino.org.uk>
 <e92d2ce5-59a0-ff65-bbfc-27072a452bfa@suse.cz>
 <alpine.DEB.2.22.394.2106111544150.479659@digraph.polyomino.org.uk>
 <5ffe3e32-ece0-a1b4-1fcf-e35177fa80b5@suse.cz>
 <alpine.DEB.2.22.394.2106231551380.13671@digraph.polyomino.org.uk>
 <87489d9a-44e2-411c-3f3a-534d07e78b95@suse.cz>
 <0866a0ea-c846-ea5e-ac7a-d1c8f106cc45@suse.cz>
 <5bb9a10d-f3b9-f16a-7430-bbae2d4978e2@suse.cz>
 <alpine.DEB.2.22.394.2106281533020.220739@digraph.polyomino.org.uk>
 <2f60f602-5d88-7674-9620-2172748664c5@suse.cz> <83a6n8obh4.fsf@gnu.org>
 <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> <83pmw3mrcg.fsf@gnu.org>
 <c1a4a4ca-f259-7a8b-007f-0d9557234507@suse.cz> <83k0makvk7.fsf@gnu.org>
 <56699e91-9e02-102e-4277-af8823cf3145@suse.cz>
 <alpine.LSU.2.20.2107011450190.25557@wotan.suse.de>
 <f26e353f-b88c-0c3c-d989-73aee2f2997b@suse.cz>
MIME-version: 1.0
Content-type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Spam-Status: No, score=2.2 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS,
 RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_PASS,
 TXREP autolearn=no autolearn_force=no version=3.4.4
X-Spam-Level: **
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on
 server2.sourceware.org
X-BeenThere: gcc@gcc.gnu.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Gcc mailing list <gcc.gcc.gnu.org>
List-Unsubscribe: <https://gcc.gnu.org/mailman/options/gcc>,
 <mailto:gcc-request@gcc.gnu.org?subject=unsubscribe>
List-Archive: <https://gcc.gnu.org/pipermail/gcc/>
List-Post: <mailto:gcc@gcc.gnu.org>
List-Help: <mailto:gcc-request@gcc.gnu.org?subject=help>
List-Subscribe: <https://gcc.gnu.org/mailman/listinfo/gcc>,
 <mailto:gcc-request@gcc.gnu.org?subject=subscribe>
X-List-Received-Date: Fri, 02 Jul 2021 10:32:30 -0000

> Cc: Eli Zaretskii <eliz@gnu.org>, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org,
>  joseph@codesourcery.com
> From: Martin Liška <mliska@suse.cz>
> Date: Fri, 2 Jul 2021 11:40:06 +0200
> 
> > It must
> > look sensible without that.  In this case it seems that already the
> > generated .texinfo input to makeinfo is bad, where does the 'e' (or 'f')
> > come from?  The original texinfo file simply contains:
> 
> These are auto-numbered. Theoretically one can use the verbose anchor names:
> 
> @anchor{demo cmdoption-Wshift-overflow3}@anchor{e}@anchor{demo cmdoption-wshift-overflow3}@anchor{f}
> @deffn {Option} @w{-}Wshift@w{-}overflow3=n, @w{-}Wshift@w{-}overflow3
> 
> Default option value for @ref{e,,-Wshift-overflow3}.
> 
> But these would lead to even longer '*note -Wshift-overflow3: demo cmdoption-wshift-overflow3' output.

While auto-numbering is a nice feature, the human-readable anchors
have an advantage of hinting on the topic to which the cross-reference
points.