From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x536.google.com (mail-ed1-x536.google.com [IPv6:2a00:1450:4864:20::536]) by sourceware.org (Postfix) with ESMTPS id 02976384F025 for ; Tue, 13 Jul 2021 12:46:46 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 02976384F025 Received: by mail-ed1-x536.google.com with SMTP id t3so32972285edc.7 for ; Tue, 13 Jul 2021 05:46:45 -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=MfFNE1gFta56kej1FZhcCjbFMfDsH0BTQ1pTnnUT1t8=; b=k/b3JenzQFfrgGR2oJ//XR0QN+oBLhNg2Gu2yHfg3bTXqDkZXnbX3f6gksu0BvnP3/ aa2g/U1HJBJdv6GSeGmhHuQMi9/UQIbrvSvfJscYXivlJz6d/q0KB63yI4jYn8RSkfqm jYgiaOVjusmSl2PgGnI7/rObIInWnwkSDqzcpUaYKTLTBkkAhlr0B8tZDIgce1v/1Uj3 PI75xopeLmDvPZzawnFcBaydNwmIQYo9qWg8UMP+eI+LTOAwPT6Ats3+OgngindlyoJJ oguZ3bZmKSNmFWsXcgDs848gZHD/A0ZJUTB6dAxYwsJL1JPhmrkY+GKE4BcW11ZIJ8H9 23XA== X-Gm-Message-State: AOAM531Xmj3S4lF/hWnepzuzP5YdzjJflzAMU9dWZjMVAgcX+eWADAM9 vQ5wIf2VuUf7Ka03StNzCi7QNuRuMXrcEGb1knyTJZ/p X-Google-Smtp-Source: ABdhPJxIoDZZSd7NtRdf070ejReys21eZGDToql2UVgQQXa3KqsKQ1c51apPF/NNrEKOFG9e0/tpnCqQ6UTBKBzqjwA= X-Received: by 2002:a05:6402:31a6:: with SMTP id dj6mr5688528edb.248.1626180405059; Tue, 13 Jul 2021 05:46:45 -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> <83y2aa8m7g.fsf@gnu.org> In-Reply-To: <83y2aa8m7g.fsf@gnu.org> From: Richard Biener Date: Tue, 13 Jul 2021 14:46:33 +0200 Message-ID: Subject: Re: Benefits of using Sphinx documentation format To: Eli Zaretskii Cc: Jonathan Wakely , GCC Development Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-3.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, 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 12:46:47 -0000 On Tue, Jul 13, 2021 at 1:52 PM Eli Zaretskii wrote: > > > 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). I can very well understand the use of the html manual when you want to share pointers to specific parts of the documentation in communications. I think that's the main motivation here - users are nowadays familiar with mouse-clicking and the web, not so much with emacs or any other way to consume texinfo documentation. I'm also not sure if there's some texinfo URI that could be used to share documentation pointers. Richard.