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 EBF31385BF81; Mon, 5 Jul 2021 12:14:23 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org EBF31385BF81 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1888 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 1m0NUU-0004GM-EN; Mon, 05 Jul 2021 08:14:22 -0400 Date: Mon, 05 Jul 2021 15:14:25 +0300 Message-Id: <83im1pgdpa.fsf@gnu.org> From: Eli Zaretskii To: Richard Sandiford Cc: hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com, richard.sandiford@arm.com In-Reply-To: (message from Richard Sandiford on Mon, 05 Jul 2021 10:17:38 +0100) 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> 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: Mon, 05 Jul 2021 12:14:25 -0000 > From: Richard Sandiford > Cc: Eli Zaretskii , gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > Date: Mon, 05 Jul 2021 10:17:38 +0100 > > 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. > > 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.) > E.g. quoting from Richard's recent patch: > > @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 > be enabled as well. Enabled at level @option{-O1} and higher, except > for @option{-Og}. > > 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. 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}) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. > 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. And besides, how would you decide which cross-references to drop and which to retain in Info?