From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from fencepost.gnu.org (fencepost.gnu.org [IPv6:2001:470:142:3::e]) by sourceware.org (Postfix) with ESMTPS id 8FDD13858039 for ; Tue, 13 Jul 2021 11:52:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8FDD13858039 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1383 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m3Gy9-00037h-2Q; Tue, 13 Jul 2021 07:52:57 -0400 Date: Tue, 13 Jul 2021 14:52:51 +0300 Message-Id: <83y2aa8m7g.fsf@gnu.org> From: Eli Zaretskii To: Richard Biener Cc: jwakely.gcc@gmail.com, gcc@gcc.gnu.org In-Reply-To: (message from Richard Biener on Tue, 13 Jul 2021 08:24:17 +0200) Subject: Re: Benefits of using Sphinx documentation format References: <1446990946.2994.192.camel@surprise> <83r1g3aady.fsf@gnu.org> <144d27f7-9486-0515-2ebd-4e8d9d9fc3b2@suse.cz> <4988937.164lfTNWpH@excalibur> <83k0lva2hv.fsf@gnu.org> 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 13 Jul 2021 11:52:59 -0000 > From: Richard Biener > Date: Tue, 13 Jul 2021 08:24:17 +0200 > Cc: Eli Zaretskii , "gcc@gcc.gnu.org" > > I actually like texinfo (well, because I know it somewhat, compare to sphinx). > 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 ...). FTR, I almost exclusively use the (Emacs) Info reader to read the manuals in Info format. I never understood those who prefer reading HTML-formatted docs in a Web browser. The advanced features of Info: the index-search with powerful completion built-in, seamless cross-references between manuals, the ability to search all of the manuals installed on my system and then browse the results, the ability to have Emacs land me at the documentation of the symbol under the cursor regardless of its language/package/library, no dependency on connectivity, to mention just a few -- all those are tremendous productivity boosters. I rarely spend more than a few seconds to find the piece of documentation I need (not including reading it, of course). (And yes, grep-style regexp search through the entire manual is also available, although I only need to use it in rare and exceptional circumstances.) So I never understood people, let alone developers, who are willing to throw such power out the window and use HTML. I only do that when there's a manual I don't have installed in the Info format (a rare phenomenon) or some other similarly exceptional cases. But I get it that there are strange people who prefer HTML nonetheless. More importantly, the Texinfo developers understand that, and actively work towards making the Texinfo HTML better, with some impressive progress already there, see the latest release 6.8 of Texinfo (Gavin mentioned some of the advances).