From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by sourceware.org (Postfix) with ESMTPS id CEC6C3855023; Mon, 12 Jul 2021 15:03:41 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org CEC6C3855023 Received: by mail-wm1-x32f.google.com with SMTP id l6so3339650wmq.0; Mon, 12 Jul 2021 08:03:41 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=nOoi0ippkThHNhMeN5ngORMb6w+eYAZSgrT4+HStupQ=; b=GBVhcgkfPyHa7nk/+chC9sggxDIwjYXCoufQuP9kOxGGOXJwyh/CO+C+72mcmAu9fD DzP2uVowjlvYl3kGp36XklonHyS3z51N8VqfL5QDNQdCRQB6Au0/5Sg1gLail+UDwfDv Bpm8oZ1m7BlEi9FGNUvbrgxm+vz2T44ONWWfx5NszUnKel5o2yTg86J5wZ3OKfJNK7VI e9v4wxdbgXG7sQmXlYTNsx3hlnmsTcv5scik7anRhSZFxYjQNdw5Jt1nbQ+wov2s7ErM QvpLlSi+z/B82cuA/gFVve5O+OkSu77mQH+azegeKh/tS3ev4FTAsAxkhLr2qJ2+m4PY I+mQ== X-Gm-Message-State: AOAM531vnPrzXyWgYkR02eUAolvIzfIe7kjRQEr7cNilhh8lrLo8DiCH kz++GWNmxPf+Yp97/2XA/hmjfwUc7J8gwWqEh9Y= X-Google-Smtp-Source: ABdhPJwu1ssII5CK/G6FpE8eJRpjxjbM5QreKjujsKuuhDkpSdqmAfy6va9xKp/GUEAiM3CKF01N/Sj/tyvrMT+VG78= X-Received: by 2002:a7b:c751:: with SMTP id w17mr26140124wmk.117.1626102220883; Mon, 12 Jul 2021 08:03:40 -0700 (PDT) MIME-Version: 1.0 References: <1446990946.2994.192.camel@surprise> <1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz> <3a2a573b-5185-fff5-f9da-6e5e39953ad6@suse.cz> <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz> <5ffe3e32-ece0-a1b4-1fcf-e35177fa80b5@suse.cz> <87489d9a-44e2-411c-3f3a-534d07e78b95@suse.cz> <0866a0ea-c846-ea5e-ac7a-d1c8f106cc45@suse.cz> <5bb9a10d-f3b9-f16a-7430-bbae2d4978e2@suse.cz> <2f60f602-5d88-7674-9620-2172748664c5@suse.cz> <83a6n8obh4.fsf@gnu.org> <57743e51-04d5-ec2e-b684-54f0321ef0bd@suse.cz> <83pmw3mrcg.fsf@gnu.org> <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> <83v95fabwx.fsf@gnu.org> <83r1g3aady.fsf@gnu.org> In-Reply-To: From: Jonathan Wakely Date: Mon, 12 Jul 2021 16:03:29 +0100 Message-ID: Subject: Re: Benefits of using Sphinx documentation format To: Eli Zaretskii Cc: =?UTF-8?Q?Martin_Li=C5=A1ka?= , "gcc@gcc.gnu.org" , gcc-patches , "Joseph S. Myers" Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-1.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, KAM_SHORT, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 12 Jul 2021 15:03:43 -0000 On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely wrote: > > On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii wrote: > > I get it that you dislike the HTML produced by Texinfo, but without > > some examples of such bad HTML it is impossible to know what exactly > > do you dislike and why. > > > > > You can't find out the anchors without inspecting (and searching) > > > the HTML source. That's utterly stupid. > > > > I don't think I follow: find out the anchors with which means and for > > what purposes? > > I want to point a user at the documentation for the -c option. I can't > do that without examining the HTML source to find the anchor, then > manually editing the URL to append the anchor. It's a tedious process, > and the result is an anchor that doesn't even point to the option but > to the text following it. The process is unnecessarily difficult and > the results are bad. > > You participated in a discussion about this very topic previously: > https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg00000.html > > > > > > And even after you do that, the anchor > > > is at the wrong place: > > > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c > > > > IME, the anchor is where you put it. If you show me the source of > > that HTMl, maybe we can have a more useful discussion of the issue. > > @item -c > @opindex c > Compile or assemble the source files, but do not link. The linking > stage simply is not done. The ultimate output is in the form of an > object file for each source file. > > Putting the @opindex before the @item causes the anchor to be placed > on the previous item, which is not desirable. GNU Hello has the same problem with its docs: https://www.gnu.org/software/hello/manual/hello.html#index-_002dg That URL is garbage because of the URL-encoded %2d character, and the fact it links to the wrong place (the description of the option, not the option itself). The former is no longer an issue for GCC (it was for many years) but the latter is still a problem. If you don't know where to find it yourself, the source is visible here: https://github.com/yugui/example/blob/master/doc/hello.texi#L208 If GNU Hello and GCC can't get this right using texinfo, maybe texinfo is not fit for purpose?