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 942703857815; Mon, 12 Jul 2021 13:40:24 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 942703857815 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:3257 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 1m2wAI-0007Nl-Uo; Mon, 12 Jul 2021 09:40:19 -0400 Date: Mon, 12 Jul 2021 16:39:58 +0300 Message-Id: <83v95fabwx.fsf@gnu.org> From: Eli Zaretskii To: Martin =?utf-8?Q?Li=C5=A1ka?= Cc: hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com In-Reply-To: <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> (message from Martin =?utf-8?Q?Li=C5=A1ka?= on Mon, 12 Jul 2021 15:25:47 +0200) Subject: Re: Benefits of using Sphinx documentation format 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> <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit 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-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, 12 Jul 2021 13:40:25 -0000 > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > From: Martin Liška > Date: Mon, 12 Jul 2021 15:25:47 +0200 > > Let's make it a separate sub-thread where we can discuss motivation why > do I want moving to Sphinx format. Thanks for starting this discussion. > Benefits: > 1) modern looking HTML output (before: [1], after: [2]): > a) syntax highlighting for examples (code, shell commands, etc.) > b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) > c) one can easily copy a link to an anchor (displayed as ¶) > d) internal links are working, e.g. one can easily jump from listing of options > e) left menu navigation provides better orientation in the manual > f) Sphinx provides internal search capability: [3] > 2) internal links are also provided in PDF version of the manual How is this different from Texinfo? > 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and libgccjit) > 4) support for various output formats, some people are interested in ePUB format Texinfo likewise supports many output formats. Someone presented a very simple package to produce epub format from it. > 5) Sphinx is using RST which is quite minimal semantic markup language Is it more minimal than Texinfo? > 6) TOC is automatically generated - no need for manual navigation like seen here: [5] That is not needed in Texinfo as well, since long ago. Nowadays, you just say @node Whatever and the rest is done automatically, as long as the manual's structure is a proper tree (which it normally is, I know of only one manual that is an exception). > Disadvantages: > > 1) info pages are currently missing Page description in TOC > 2) rich formatting is leading to extra wrapping in info output - beings partially addresses in [4] > 3) one needs e.g. Emacs support for inline links (rendered as notes) 4) The need to learn yet another markup language. While this is not a problem for simple text, it does require a serious study of RST and Sphinx to use the more advanced features. 5) Lack of macros. AFAIK, only simple textual substitution is available, no macros with arguments.