From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by sourceware.org (Postfix) with ESMTP id 4F0CD388F011 for ; Mon, 12 Jul 2021 16:36:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4F0CD388F011 Received: from mail-qk1-f197.google.com (mail-qk1-f197.google.com [209.85.222.197]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-25-ibQpWnz3NaSr2ax9dL2VeQ-1; Mon, 12 Jul 2021 12:36:09 -0400 X-MC-Unique: ibQpWnz3NaSr2ax9dL2VeQ-1 Received: by mail-qk1-f197.google.com with SMTP id j9-20020a05620a0009b02903b770762a3cso4507489qki.17 for ; Mon, 12 Jul 2021 09:36:09 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:message-id:subject:from:to:cc:date:in-reply-to :references:user-agent:mime-version:content-transfer-encoding; bh=IMW2dGI7H4WTiDy6qo3pPT5AK30hyC0BQhxqcjdQNIM=; b=UtY0c7IqnCSRyS4AOTG9H7StIQgnp/b2pxTaMokctOLGe3KR9phreuJZ8FGIOgDA87 GGp5FN0PO0WADrgo1kiNm5skqhF6B3WowIdvYjzFfjx02EnuLh5+dLd7J6FeAlrlIzb1 XqKtqm1APfFGXHR/MbjvzQR8Np8Lacs7h1OtM4gZ7PO3R4+1xQWlaO+8DLam5piETgBB KzB6XuxEHZCD0pexmi6eb4jou3gVG0tgWnxxKIqwITCrbfyXACyXbX96bVF3Y5Ibib+Z nlJ27qOdlKzhQUHPKkqtU9qAr8vrZnI1/CtufPtmCbstxlLvSfa6LWtXhmrBn5t13Iu6 6kEg== X-Gm-Message-State: AOAM531KuKvJDR4VFmcLF4xlRHMC2vntHpSFw7VXT/NWor43h3jQkTlX XWEvJZis3bN0rebkn+3lR3/N6ZEYdfx8iYpISFCVlctuWwQqbXiGk805r3Lfq5LA36K/O1VsTiN /2iewZso= X-Received: by 2002:a05:620a:406:: with SMTP id 6mr6603501qkp.451.1626107768997; Mon, 12 Jul 2021 09:36:08 -0700 (PDT) X-Google-Smtp-Source: ABdhPJy1ZC0Fxym6Fi8O5W2JEMFXgkoJXsZGrAI9jJpADLGHYd8UXwtYaIl4cRR08HTeN0IUh4zsgQ== X-Received: by 2002:a05:620a:406:: with SMTP id 6mr6603471qkp.451.1626107768740; Mon, 12 Jul 2021 09:36:08 -0700 (PDT) Received: from t14s.localdomain (c-73-69-212-193.hsd1.nh.comcast.net. [73.69.212.193]) by smtp.gmail.com with ESMTPSA id h68sm6840217qkf.126.2021.07.12.09.36.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 12 Jul 2021 09:36:08 -0700 (PDT) Message-ID: <2f1b08cb5c9057eef204d872fe667c74596d323b.camel@redhat.com> Subject: Re: Benefits of using Sphinx documentation format From: David Malcolm To: Martin =?UTF-8?Q?Li=C5=A1ka?= , Hans-Peter Nilsson , Eli Zaretskii Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com Date: Mon, 12 Jul 2021 12:36:06 -0400 In-Reply-To: <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> 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> User-Agent: Evolution 3.38.4 (3.38.4-1.fc33) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.3 required=5.0 tests=BAYES_00, BODY_8BITS, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, 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 16:36:15 -0000 On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote: > Hello. > > Let's make it a separate sub-thread where we can discuss motivation > why > do I want moving to Sphinx format. > > Benefits: > 1) modern looking HTML output (before: [1], after: [2]): "modern looking" is rather subjective; I'd rate Sphinx's output as looking like it's from 2010s (last decade), whereas Texinfos' looks like it's from the 1990s. In theory this ought not to matter, but every time I look at our documentation it gives me a depressing feeling, reminiscent of a graveyard, that discourages me from fixing things. >     a) syntax highlighting for examples (code, shell commands, etc.) ...with support for multiple programming languages, potentially on the same page. For example, in the libgccjit docs: https://gcc.gnu.org/onlinedocs/jit/intro/tutorial02.html we can have a mixture of C, assembler and shell on one page, and each example is syntax-highlighted accordingly. It's not clear to me how to do that in texinfo, since there needs to be a way to express what language an example is in. >     b) precise anchors, the current Texinfo anchors are not displayed > (start with first line of an option) ...and the URLs are sane and stable (so e.g. there is a reliable, guessable, readable URL for the docs for say, "-Wall"). >     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] ...also (quoting myself in places here from 2015 https://gcc.gnu.org/pipermail/gcc-patches/2015-November/434055.html ): * the ability to include fragments of files: libgccjit's documentation uses directives to include code from the test suite, so that all of the code examples are also part of the test suite, and are thus known to compile), allowing for (almost) literate programming. [That said, the build of libgccjit's docs on gcc.gnu.org seems to be missing those fragments; I wonder if there's a path or version issue?] * a page-splitting structure that make sense, to me, at least (I have never fathomed the way texinfo's navigation works, for HTML, at least, and I believe I'm not the only one; I generally pick the all-in-one- HTML-page option when viewing texinfo-html docs and do textual searches, since otherwise I usually can't find the thing I'm looking for (or have to resort to a brute-force depth-first search of clicking through the links).) * much more use of markup, with restrained and well-chosen CSS (texinfo's HTML seems to ignore much of the inline markup in the .texinfo file) > 2) internal links are also provided in PDF version of the manual > 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 > 5) Sphinx is using RST which is quite minimal semantic markup language Sphinx is also used by many high-profile FLOSS projects (e.g. the Linux kernel, LLVM, and the Python community), so it reduces the barrier to entry for new contributors, relative to texinfo. > 6) TOC is automatically generated - no need for manual navigation > like seen here: [5] > > 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) > > I'm willing to address issue 1) in next weeks and I tend to skip > emission of links as mentioned in 3). > Generally speaking, I'm aware that some people still use Info, but I > think we should more focus > on more modern documentation formats. That's HTML (and partially > PDF). I think the output formats we need to support are: - HTML - PDF - man page (hardly "modern", but still used) I regared "info" as merely "nice to have" - I don't know anyone who uses it other than some core GNU contributors. Dave > > Martin > > [1] > https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing > [2] > https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing > [3] > https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default# > [4] https://github.com/sphinx-doc/sphinx/pull/9391 > [5] @comment node-name,     next,          previous, up >      @node    Installing GCC, Binaries, , Top >