From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lxmtout1.gsi.de (lxmtout1.gsi.de [140.181.3.111]) by sourceware.org (Postfix) with ESMTPS id 1CD743888C63 for ; Mon, 12 Jul 2021 14:54:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 1CD743888C63 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=gsi.de Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gsi.de Received: from localhost (localhost [127.0.0.1]) by lxmtout1.gsi.de (Postfix) with ESMTP id 960332050D02 for ; Mon, 12 Jul 2021 16:54:51 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at lxmtout1.gsi.de Received: from lxmtout1.gsi.de ([127.0.0.1]) by localhost (lxmtout1.gsi.de [127.0.0.1]) (amavisd-new, port 10024) with LMTP id t-rmUlb2gI9x for ; Mon, 12 Jul 2021 16:54:51 +0200 (CEST) Received: from srvex3.campus.gsi.de (unknown [10.10.4.16]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by lxmtout1.gsi.de (Postfix) with ESMTPS id 7F1B12050D00 for ; Mon, 12 Jul 2021 16:54:51 +0200 (CEST) Received: from excalibur.localnet (140.181.3.12) by srvex3.campus.gsi.de (10.10.4.16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.2242.10; Mon, 12 Jul 2021 16:54:50 +0200 From: Matthias Kretz To: Subject: Re: Benefits of using Sphinx documentation format Date: Mon, 12 Jul 2021 16:54:50 +0200 Message-ID: <4988937.164lfTNWpH@excalibur> Organization: GSI Helmholtzzentrum =?UTF-8?B?ZsO8cg==?= Schwerionenforschung In-Reply-To: <144d27f7-9486-0515-2ebd-4e8d9d9fc3b2@suse.cz> References: <1446990946.2994.192.camel@surprise> <83r1g3aady.fsf@gnu.org> <144d27f7-9486-0515-2ebd-4e8d9d9fc3b2@suse.cz> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="UTF-8" X-Originating-IP: [140.181.3.12] X-ClientProxiedBy: SRVEX2.campus.gsi.de (10.10.4.15) To srvex3.campus.gsi.de (10.10.4.16) X-Spam-Status: No, score=-4.9 required=5.0 tests=BAYES_00, BODY_8BITS, KAM_DMARC_STATUS, SPF_HELO_PASS, 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:54:55 -0000 Hi. I'm commenting as a long-time GCC user and reader of the manual (never via= =20 info reader, mostly via DuckDuckGo / Google -> HTML docs) who recently star= ted=20 contributing more than just PRs. 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 without > > some examples of such bad HTML it is impossible to know what exactly > > do you dislike and why. I believe Martin made a really good list. But FWIW, when I reach the GCC HTML docs it's like a blast from the past. I= t=20 looks more or less exactly like web pages looked in the 90ies. To me, that= =20 gives GCC an image of an old and sluggishly moving project. And to me that'= s a=20 high priority issue. I have to size down the browser window so that line lengths are bearable. I= =20 have to scroll to the top/bottom of the page for navigation. Navigating=20 through the tree of pages requires you to learn how it works; it's not=20 intuitive at all. If the decision for how to write and read documentation places 'info' in=20 higher priority than HTML then that would emphasize "the image of an old an= d=20 sluggishly moving project" even more than the sight of the HTML pages. Who = is=20 the target audience? > >>> 4) The need to learn yet another markup language. > >>> =20 > >>> While this is not a problem for simple text, it does require a > >>> serious study of RST and Sphinx to use the more advanced feature= s. > >>=20 > >> This is a problem with texinfo too. > >=20 > > 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. >=20 > Yes, people will have to learn a new syntax. Similarly to transition of S= VN, > people also had to learn with a more modern tool. Same issue. Is the goal to accommodate only seasoned GNU contributors?=20 Basically everyone nowadays knows and uses Markdown. RST is not far from th= at.=20 So it opens up the project for way more people to contribute. I wrote=20 documentation patches recently. I found it really awkward to write. Markup= =20 languages have gotten better and I really hope we can move on! > >>> 5) Lack of macros. > >>> =20 > >>> AFAIK, only simple textual substitution is available, no macros > >>> with arguments. I don't recall for sure, but I think I did that with RST at some point. Best, Matthias =2D-=20 =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80 Dr. Matthias Kretz https://mattkretz.github.io GSI Helmholtz Centre for Heavy Ion Research https://gsi.de std::experimental::simd https://github.com/VcDevel/std-simd =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80= =E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2= =94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94= =80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80=E2=94=80