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 A2818385800E; Mon, 5 Jul 2021 09:17:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A2818385800E 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 3A6661063; Mon, 5 Jul 2021 02:17:40 -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 6651C3F5A1; Mon, 5 Jul 2021 02:17:39 -0700 (PDT) From: Richard Sandiford To: Hans-Peter Nilsson Mail-Followup-To: Hans-Peter Nilsson , Eli Zaretskii , gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com, richard.sandiford@arm.com Cc: Eli Zaretskii , 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> Date: Mon, 05 Jul 2021 10:17:38 +0100 In-Reply-To: (Hans-Peter Nilsson's message of "Fri, 2 Jul 2021 19:53:50 -0400 (EDT)") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain 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-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 05 Jul 2021 09:17:42 -0000 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. IMO this subthread has demonstrated why the limitations of info formatting have held back the amount of cross-referencing in the online html. (And based on emperical evidence, I get the impression that far more people use the online html docs than the info docs.) 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. Adding the extra references to the html (and pdf) output but dropping them from the info sounds like a good compromise. Thanks, Richard