From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x52e.google.com (mail-ed1-x52e.google.com [IPv6:2a00:1450:4864:20::52e]) by sourceware.org (Postfix) with ESMTPS id CF5013857005 for ; Tue, 13 Jul 2021 06:24:29 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org CF5013857005 Received: by mail-ed1-x52e.google.com with SMTP id h2so31644355edt.3 for ; Mon, 12 Jul 2021 23:24:29 -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=yTI+Nw8SDBqR12K4vAzQI61vVh2OzZjnhX8HMhlV+mU=; b=GO24aNXjlhQfX4fWcdgO0LiEUWzb58V7kawsrvGhK30KYss7g9//un6XBqb5lVSOK5 ImSmaGtF7h9LF5U8NNvbI+nAHXXs89JXDm/LuvSrNloepVIhzcyZS+G/eiK3aLCL6G5q YM2fFjepVGvdGoxPj0AQN/vY+OzStipPJY+tRliy2G4Mp4VnwtmlmS8Felqn+bkdhJY6 gOmjM1t2/PrJYwM3Ug+ouhT/wslMzB5e8Lleyfq3EfP5hCvai9ofDA84uaBdqoDNea/R kDXiGhDoLnvzRGfn9nf+KxSRQdwHpfPV5CbdUWMG3T78bVopFAkVY5/nIa1/CIfDGkfC 9WpA== X-Gm-Message-State: AOAM53267IExgcwt6pvtJis7+zQqGCr0dBV95rFRqKtnx1BGwF2e9PJv q10A18yeit+GwfWeGPuKbmGfhtAJLFyW21obXTQ= X-Google-Smtp-Source: ABdhPJyK4wSIqP3y94W9SQ5SPFdR/wUMWt8rOvl2JzjalMw3KT7DFRrtPgZLh6aiNHEX7oAZcrLCu3ZqRMuYBMuvBUU= X-Received: by 2002:aa7:c808:: with SMTP id a8mr3544524edt.245.1626157468800; Mon, 12 Jul 2021 23:24:28 -0700 (PDT) MIME-Version: 1.0 References: <1446990946.2994.192.camel@surprise> <83r1g3aady.fsf@gnu.org> <144d27f7-9486-0515-2ebd-4e8d9d9fc3b2@suse.cz> <4988937.164lfTNWpH@excalibur> <83k0lva2hv.fsf@gnu.org> In-Reply-To: From: Richard Biener Date: Tue, 13 Jul 2021 08:24:17 +0200 Message-ID: Subject: Re: Benefits of using Sphinx documentation format To: Jonathan Wakely Cc: Eli Zaretskii , "gcc@gcc.gnu.org" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-2.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: Tue, 13 Jul 2021 06:24:31 -0000 On Mon, Jul 12, 2021 at 7:20 PM Jonathan Wakely via Gcc w= rote: > > On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc wro= te: > > > > > From: Matthias Kretz > > > Date: Mon, 12 Jul 2021 16:54:50 +0200 > > > > > > On Monday, 12 July 2021 16:30:23 CEST Martin Li=C5=A1ka wrote: > > > > On 7/12/21 4:12 PM, Eli Zaretskii wrote: > > > > > I get it that you dislike the HTML produced by Texinfo, but witho= ut > > > > > some examples of such bad HTML it is impossible to know what exac= tly > > > > > do you dislike and why. > > > > > > I believe Martin made a really good list. > > > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that > > list. However, his message didn't get through to the list, for some > > reason. > > It did: > https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html > https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html > > The HTML attachment has been stripped though. The relevant part of the > HTML looks like this: > >
--greeting=3Dtext href=3D'#index-_002d_002dgreeting' class=3D'copiable-anchor'> > ¶
>
-g text
>
>

Output text instead of the default greeting. >

>
> > Note the anchor that is part of the
element, > not the
(where the index-__002d anchor is still located). > > > > Can someone please see why, and release his message? I think > > he makes some important points, and his message does deserve being > > posted and read as part of this discussion. > > He shows that some of the linking issues are addressed in the latest > texinfo release, which is great. But it doesn't negate all Martin's > other points. > > GCC devs and users who frequently modify or refer to the HTML docs > want to replace texinfo. One vocal objector who just keeps repeating > that texinfo is fine should not block that progress. You mean one very vocal and one active developers want to replace it? I actually like texinfo (well, because I know it somewhat, compare to sphin= x). I think it produces quite decent PDF manuals. I never use the html output (in fact I read our manual using grep & vim in the original .texi form ...). But then I'm mostly of the who-does-the-work-decides attitude - so if there are people driving a transition to sphinx because they want to improve sth and they don't manage to do that with texinfo (for whatever reason) then OK= . As long as it doesn't regress my personal usecase (I hope the sphinx docs are still digestable in source form, which I understand they are). Just I really suggest to not claim its texinfos fault. It's likely not. It's likely the fault of GCCs manual being "old" and hasn't catched up with new texinfo features. And where texinfo has bugs they likely can be fixed. Just my (final) 2c to this discussion. Richard.