From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.220.28]) by sourceware.org (Postfix) with ESMTPS id A289B388982B; Mon, 12 Jul 2021 14:37:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org A289B388982B Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.cz Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.cz Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id C249122166; Mon, 12 Jul 2021 14:37:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1626100620; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hi0jtkX8ztQBtUykpyAhTtN6jVUTG/cTgi+yjo6cbpk=; b=WHzzSY9AotHmcsUHCSFHV+I+caZMGlvjvivam7y1OSju5GCpFVsuZhp8fFKU7yCxIpT0pW y5RK1qSUqvm1CK5oy3yqVcsxfur/IbliyJhA0pOcZPMkPWq1++A+TZxKdWZLgWqO/BXQ1I rE1oWCNNHpTgBm9DAgvgeinmI+nyrBY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1626100620; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hi0jtkX8ztQBtUykpyAhTtN6jVUTG/cTgi+yjo6cbpk=; b=sPKk2x95Y9pB3Q9nWRuXF/+R9qdfJkdUpVq+Csfd30WmT8RngDoaDHuYgGf1UD5uJVROtR 6H+DGkWmwnIG9vCA== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id 9E50613BAF; Mon, 12 Jul 2021 14:37:00 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id WeGAJYxT7GCBfgAAMHmgww (envelope-from ); Mon, 12 Jul 2021 14:37:00 +0000 Subject: Re: Benefits of using Sphinx documentation format To: Eli Zaretskii Cc: hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com References: <1446990946.2994.192.camel@surprise> <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> <83v95fabwx.fsf@gnu.org> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: Date: Mon, 12 Jul 2021 16:37:00 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0 MIME-Version: 1.0 In-Reply-To: <83v95fabwx.fsf@gnu.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-5.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, NICE_REPLY_A, 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, 12 Jul 2021 14:37:02 -0000 On 7/12/21 3:39 PM, Eli Zaretskii wrote: >> 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? Texinfo does not emit them. See e.g. links in option listing (-O2, -Os, ...). > >> 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. Good to know. > >> 5) Sphinx is using RST which is quite minimal semantic markup language > > Is it more minimal than Texinfo? I would say that's pretty easy to learn, similarly complex as 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). All right, then we likely do an extra work right now. > >> 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. No, majority of the documentation is pretty simple: basic formatting, links, tables and code examples. Martin > > 5) Lack of macros. > AFAIK, only simple textual substitution is available, no macros > with arguments. >