From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by sourceware.org (Postfix) with ESMTPS id 71E403855023; Mon, 12 Jul 2021 14:52:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 71E403855023 Received: by mail-wm1-x333.google.com with SMTP id u8-20020a7bcb080000b02901e44e9caa2aso177092wmj.4; Mon, 12 Jul 2021 07:52:18 -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:content-transfer-encoding; bh=rvRUu9eygVsgErNTRurN1ahrhJSFmpy6YpMAaeOCfnM=; b=Xpu+TYtO9f8HulhppGhLUgKTi7LVf5XSXBYTZT8wLWfHxw+sYZbZ24qlh2kMUFZ1yV Xj3D8OEImUl5+TtoDX/nx3iyqyueXaF1Htk8GKz5KHaQSkdjO1m2LqNi2ZYQluiDIWRY emsQc0FVHBBAVoObGFD6SiWP5rius54UFzVoklRtqHtmOUSojVbqz1kW928cXQdztmvx Lzs6ndiv8ruObM3Kn4LDy/s4BtXruCTyjc1csJ30oGPDXjod2fwNIrgBoB8d2blslONY 95cySmDEriH2uxVPnBMdRcXn1dIkIze6FjN0rrfHOg/WOBe4+EKOsZeXLA4EadTc501Q Ju4w== X-Gm-Message-State: AOAM532xwr7ZQERyhhGhT+lmoo18uBkHtSK+bvc8ap1Nm+fFh/+q7Bef 6TAHm0/QLIzriD9yU8EWvwa6n4x8hU0JzYF/mVc= X-Google-Smtp-Source: ABdhPJznmNg6BugFWlkKt0TTaZ/BFvfLLj99o+JnWIy4xl1J+9ygUy3HKUxFqAyd5rHEuEIxS5+eQdzc4+uTsLwfdtU= X-Received: by 2002:a7b:cd17:: with SMTP id f23mr23980534wmj.106.1626101537321; Mon, 12 Jul 2021 07:52:17 -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: <83r1g3aady.fsf@gnu.org> From: Jonathan Wakely Date: Mon, 12 Jul 2021 15:52:05 +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" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-1.8 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 14:52:20 -0000 On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii wrote: > > > From: Jonathan Wakely > > Date: Mon, 12 Jul 2021 14:53:44 +0100 > > Cc: Martin Li=C5=A1ka , > > "gcc@gcc.gnu.org" , gcc-patches , > > "Joseph S. Myers" > > > > For me, these items are enough justification to switch away from > > texinfo, which produces crap HTML pages with crap anchors. > > If we want to have a serious discussion with useful conclusions, I > suggest to avoid "loaded" terminology. But the results *are* crap. > > 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. > > > As somebody who spends a lot of time helping users on the mailing > > list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo > > HTML has angered me for many years. > > As somebody who spends a lot of time helping users on every possible > forum, and as someone who has wrote a lot of Texinfo, I don't > understand what angers you. Please elaborate. I don't know what part of my email you don't understand. The HTML anchors that texinfo creates are in the wrong place, and not "discoverable". If you don't understand that, then you're clearly not using the GCC HTML docs, and so I'm not surprised you think there's no reason to ditch texinfo. As a regular user of the HTML (for myself and end users of GCC), the HTML output has major usability problems. > > Yes, some people like texinfo, but some people also dislike it and > > there are serious usability problems with the output. I support > > replacing texinfo with anything that isn't texinfo. > > "Anything"? Even plain text? I hope not. Plain text with a tool to generate good HTML might be better than texinfo. > See, such "arguments" don't help to have a useful discussion. Your insistence that texinfo is fine doesn't either. It's not fine. > > > 4) The need to learn yet another markup language. > > > While this is not a problem for simple text, it does require a > > > serious study of RST and Sphinx to use the more advanced features= . > > > > This is a problem with texinfo too. > > Not for someone who already knows Texinfo. We are talking about > switching away of it, so I'm thinking about people who contributed > patches for the manual in the past. They already know Texinfo, at > least to some extent, and some of them know it very well. I've contributed dozens of patches to the manual, and I don't want to have to use texinfo to do it in future. > > > 5) Lack of macros. > > > AFAIK, only simple textual substitution is available, no macros > > > with arguments. > > > > Is this a problem for GCC docs though? > > I don't know. It could be, even if it isn't now. So not a problem then.