From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by sourceware.org (Postfix) with ESMTP id 2499A3857409; Mon, 5 Jul 2021 13:03:26 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2499A3857409 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 9FA54D6E; Mon, 5 Jul 2021 06:03:25 -0700 (PDT) Received: from localhost (e121540-lin.manchester.arm.com [10.32.98.126]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id CA7FD3F73B; Mon, 5 Jul 2021 06:03:24 -0700 (PDT) From: Richard Sandiford To: Eli Zaretskii Mail-Followup-To: Eli Zaretskii , hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com, richard.sandiford@arm.com Cc: hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com Subject: Re: [PATCH] Port GCC documentation to Sphinx 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> <83im1pgdpa.fsf@gnu.org> Date: Mon, 05 Jul 2021 14:03:23 +0100 In-Reply-To: <83im1pgdpa.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 05 Jul 2021 15:14:25 +0300") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-6.4 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, 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, 05 Jul 2021 13:03:27 -0000 Eli Zaretskii writes: >> Hans-Peter Nilsson writes: >> > I've read the discussion downthread, but I seem to miss (a recap >> > of) the benefits of moving to Sphinx. Maybe other have too and >> > it'd be a good idea to repeat them? Otherwise, the impression >> > is not so good, as all I see is bits here and there getting lost >> > in translation. >>=20 >> Better cross-referencing is one big feature. > > See below: the Info format has some features in addition to > cross-references that can make this a much smaller issue. HTML has > just the cross-references, so "when you are a hammer, every problem > looks like a nail". > >> IMO this subthread has demonstrated why the limitations of info >> formatting have held back the amount of cross-referencing in the >> online html. > > I disagree with this conclusion, see below. > >> (And based on emperical evidence, I get the impression that far more >> people use the online html docs than the info docs.) > > HTML browsers currently lack some features that make Info the format > of choice for me when I need to use the documentation efficiently. > The most important feature I miss in HTML browsers is the index > search. A good manual usually has extensive index (or indices) which > make it very easy to find a specific topic one is looking for, > i.e. use the manual as a reference (as opposed as a first-time > reading, when you read large portions of the manual in sequence). > > Another important feature is regexp search across multiple sections > (with HTML you'd be forced to download the manual as a single large > file for that, and then you'll probably miss regexps). > > Yet another feature which, when needed, is something to kill for, is > the "info apropos" command, which can search all the manuals on your > system and build a menu from the matching sections found in different > manuals. And there are a few more. > > (Texinfo folks are working on JavaScript code to add some missing > capabilities to Web browsers, but that effort is not yet complete.) Whether info or HTML is the better format isn't the issue though. The point is that we do have HTML output that is (emperically) widely used. And at the moment it isn't as good as it could be. The question that I was replying to was: what is the benefit of moving to Sphinx? And one of the answers is that it improves the HTML output. >> E.g. quoting from Richard's recent patch: >>=20 >> @item -fmove-loop-stores >> @opindex fmove-loop-stores >> Enables the loop store motion pass in the GIMPLE loop optimizer. This >> moves invariant stores to after the end of the loop in exchange for >> carrying the stored value in a register across the iteration. >> Note for this option to have an effect @option{-ftree-loop-im} has to= =20 >> be enabled as well. Enabled at level @option{-O1} and higher, except= =20 >> for @option{-Og}. >>=20 >> In the online docs, this will just be plain text. Anyone who doesn't >> know what -ftree-loop-im is will have to search for it manually. > > First, even if there are no cross-references, manual search is not the > best way. It is much easier to use index-search: > > i ftree TAB > > will display a list of options that you could be after, and you can > simply choose from the list, or type a bit more until you have a > single match. Here too I was talking about this being plain text in the online docs, i.e. in the HTML. In HTML the user-friendly way of letting users answer the question =E2=80=9Cwhat on earth is -ftree-loop-im=E2=80=9D is to have =E2=80=9C-ftre= e-loop-im=E2=80=9D be a hyperlink that goes straight to the documentation of the option. Same for PDF when viewed digitally. One of the things that the move to Sphinx does is give us those hyperlinks. > Moreover, adding cross-references is easy: > > @item -fmove-loop-stores > @opindex fmove-loop-stores > Enables the loop store motion pass in the GIMPLE loop optimizer. This > moves invariant stores to after the end of the loop in exchange for > carrying the stored value in a register across the iteration. > Note for this option to have an effect @option{-ftree-loop-im} > (@pxref{Optimize Options, -ftree-loop-im})=20 > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > has be enabled as well. Enabled at level @option{-O1} and higher, > except for @option{-Og}. > > If this looks like too much work, a simple Texinfo macro (two, if you > want an anchor where you point) will do. But this would be redundant in HTML: =E2=80=9Cfoo (see foo)=E2=80=9D. Also, the benefit of hyperlinks in HTML (not info) is that they can be used outside of prose, such as in lists, without interrupting the flow. >> Adding the extra references to the html (and pdf) output but dropping >> them from the info sounds like a good compromise. > > But that's not what happens. Not in the original patch, sure, but it's what I think Martin was suggesting as a compromise (maybe I misunderstood). The comment above was supposed to be in support of doing that. It sounds like those who use the info format (which includes me btw, at least occasionally) are happy with the status quo in terms of which links are present. So the new links could be a non-info-only feature. Thanks, Richard