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 D73923857007 for ; Mon, 9 Aug 2021 12:04:29 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D73923857007 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 imap1.suse-dmz.suse.de (imap1.suse-dmz.suse.de [192.168.254.73]) (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 B510521DB4; Mon, 9 Aug 2021 12:04:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1628510668; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qUM6tJLH9OS+9kx8/rEjT6egEse9qeiSruqVvJBhXbA=; b=xjbHAYZc0V/kPIXbkQ49VINuxPWGna07pqAD6b4+Y15mvIxU2PUGJttif6qXjoQJR82FBu uZSuxvYc+9ge5sUVIrFX9l3pi1ici1p+Vgz6jZ9dVBBcq7EPyx8hj+nA0PbUdvjkq3FZqS PEcdTfbRSuK7DDVqSY6wUKOxtTFxIM0= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1628510668; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qUM6tJLH9OS+9kx8/rEjT6egEse9qeiSruqVvJBhXbA=; b=yOgvUfL3f2pYkM9nycel5vHR8SoMnJQ55gF9SJMpeSZ6tGYQd3K9sxCM1APrSYDRztprwf b3gJHcncKpIk0nCg== Received: from imap1.suse-dmz.suse.de (imap1.suse-dmz.suse.de [192.168.254.73]) (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 imap1.suse-dmz.suse.de (Postfix) with ESMTPS id 9F80B136C1; Mon, 9 Aug 2021 12:04:28 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap1.suse-dmz.suse.de with ESMTPSA id gdedJcwZEWHEWwAAGKfGzw (envelope-from ); Mon, 09 Aug 2021 12:04:28 +0000 Subject: Re: Benefits of using Sphinx documentation format To: Gavin Smith , gcc@gcc.gnu.org References: From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <2c3670ab-19d8-0e3d-e70e-a76de0cc4ec8@suse.cz> Date: Mon, 9 Aug 2021 14:04:28 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_50, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no 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, 09 Aug 2021 12:04:32 -0000 On 7/12/21 7:49 PM, Gavin Smith via Gcc wrote: > (Sending mail again, without attachments this time in the hope it gets through.) > > I had the discussion about moving documentation of gcc from Sphinx to > Texinfo brought to my attention. > > https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html > > Speaking as the Texinfo maintainer, I hope to add my views and > understandings of things to this discussion to improve your > understanding of the facts and possibilities, although of course it's > up to you whether you use Texinfo or not. Hello. Appreciate your time spent working on the tool and I'm going to briefly reply your points. > > I will work through the points made in that email but haven't read any > of the subsequent discussion yet - I'll follow up on anything else > afterwards. > >> Benefits: >> 1) modern looking HTML output (before: [1], after: [2]): > >> a) syntax highlighting for examples (code, shell commands, etc.) > > Syntax highlighting has been achieved with Texinfo before. See > > https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html > > and > > https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html > > With Texinfo 6.8, syntax highlighting in multiple languages is easier > to achieve by giving an argument to the @example command > (https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html). > This puts a class attribute on the HTML element which can then be > picked up by a post-processor. It might also be possible to achieve > syntax highlighting with a customization file used by the Texinfo > tools themselves: see > https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html. If I understand correctly, that would need a further post-processing of the HTML elements. Sphinx works out of the box and the same output is achieved also for PDF output. > >> 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 ΒΆ) > > Similar anchors were implemented in Texinfo 6.8. See > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html > and hover any of the options there with your mouse; you will see the > pilcrow sign appear. Good. > >> e) left menu navigation provides better orientation in the manual > > Left menu navigation is possible with the new JavaScript interface, in > Texinfo 6.8. There is still a demo at > > https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html > > and > > https://per.bothner.com/tmp/Kawa-txjs/Community.html To be honest, it looks still quite legacy and I don't want to spend more working on a custom CSS template and reasonable JS functionality. I would like to take an existing theme that looks nice and provides reasonable capability. That's for me https://github.com/readthedocs/sphinx_rtd_theme > > However, I would say that it isn't necessarily always an improvement, > if it is going to be buggy. When I click on the link > https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing > the browser doesn't scroll the sidebar so to show the active ToC entry > (although it > is displayed correctly when I refresh the page). If I open a new tab, a browser correctly scrolls to the option documentation. > > The more sophisticated the HTML/JS becomes the more likely there are > these little nits. > >> f) Sphinx provides internal search capability: [3] > > There is a global search facility with the JavaScript interface > although different to that provided by Sphinx, only showing one match > at a time. As said, it's a limitation to me. > > Try > > https://per.bothner.com/tmp/Kawa-txjs/index.html > > and then press "s" on your keyboard, type in your search string (e.g. > "composable") and it will search through the manual for that string. > To go to the next match, press "s" then Return. > > The proviso about "sophisticated" HTML still applies here, though. > >> 2) internal links are also provided in PDF version of the manual > > Links already work when viewing a PDF on a computer. > > If you want to add additional links that only appear in PDF and HTML > and not in Info, this is easily achieved with a conditional macro, > like > > @ifset morelinks > @macro link{arg} > @ref{\arg\} > @end macro > @end ifset > @ifclear morelinks > @macro link{arg} > \arg\ > @end macro > @end ifclear > > followed by "@set morelinks" or "@clear morelinks" as required. All right, that would likely require providing more anchors in the existing GCC documentation. > >> 5) Sphinx is using RST which is quite minimal semantic markup language > > This is really an ineffable question of taste on which it is hard to > be convinced, but I have to point out that Texinfo is minimalistic, > with only three special characters (@, { and }). > >> 6) TOC is automatically generated - no nee6d for manual navigation like seen here: [5] >> 5] @comment node-name, next, previous, up >> @node Installing GCC, Binaries, , Top > > This is a completely bogus point with these explicit "pointers" being > optional. I couldn't find out easily how long ago these pointers > became optional, but it is at least twenty years ago. Got that, thus we use unnecessary syntax right now. > > A couple of other points, not mentioned in the original email: > * One possible disadvantage of moving away from Texinfo which might be > easily missed is support for reliable web links between different > manuals. If you change format you should make sure that these work, > e.g. if you reference the glibc manual the web link to that should > work correctly (as well as the link working in the Info format). Good point, I'm not aware of any cross links. If there are any, I'm willing to update them. > * A disadvantage of focusing on HTML output is that locally installed > documentation gets sidelined: although locally installed HTML > documentation is possible, it tends not to happen and people refer to > the web version instead, with all of its disadvantages (slow speed, > may be the wrong version or disappear off the web, lack of user > privacy). Another disadvantage of HTML is that links can only go to > one place, while with the Info format you can have manuals installed > in several places, even more than one version of a manual installed at > once. Totally misleading. I don't see why would anybody install HTML documentation locally. Our motivation is to have HTML documentation on our site, where we can update it and Google can index it for people using full text search. > > Some people don't realise that Texinfo is actively maintained and > there is a mailing list at bug-texinfo@gnu.org > (https://lists.gnu.org/mailman/listinfo/bug-texinfo); this is a place > for people to discuss their needs as to what they need from the > system. I wonder if some of the desiderata can be satisfied with > existing facilities in Texinfo or if not if we could accommodate them > with not too much difficulty. As mentioned, I appreciate your work. On the other hand, Sphinx documentation community is much bigger and the list of projects using the tool is pretty huge: https://www.sphinx-doc.org/en/master/examples.html (include huge FOSS projects like LLVM, or Linux kernel). That makes me believe the transition makes sense and we will benefit from it as project. Martin