From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by sourceware.org (Postfix) with ESMTPS id 228AD3857815; Mon, 12 Jul 2021 13:53:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 228AD3857815 Received: by mail-wm1-x32b.google.com with SMTP id l17-20020a05600c1d11b029021f84fcaf75so4688829wms.1; Mon, 12 Jul 2021 06:53:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=fVtOsrEwt1qfglDuDu3yxVGYZYk/JvxVK+TeINAimAQ=; b=ebmZIZhvVoaIkwRuOxnGSGhmo8IhLtxXk2RKCSdhVyIyVHYE8b47ZxoONozqLG2rEg dunMu3Gb7Gxv3nrkVrvMTge6Fkf8JaIwaHMHJNgFVHTKr+tXLYz/Gd04iqAl7UBpZ4Qe dRp231KMP7xyn4SFCStTh9VWlCB9PLTcNbJpfagRddeKgOXHTbD0Ci5gfb3z0vNzEYCR Mw+8CsS5YIT8ukdaobRVB/8Kd8lXOSfbeSqDIgz/vltoj9AueKKe+nYbmVXFQIN4rh7q suqT6MUB3I+KGPNuMy0dHHkJnRiT8AnPRAoMZHzsy3LqDI3sRmXSHoQEFPnAp/oS9gZ7 H5Fg== X-Gm-Message-State: AOAM532C2zUwnhfcdmDmBuh0o+xbQ1oNSVxjaN5I7n62bcVGkpiD/Q4a Hqa/Kj+F6fNEFfdo4/AoOkAx2SwR9hhUA/ioC5Q= X-Google-Smtp-Source: ABdhPJwbq31piZk9dSkTkOLtz/AWR7TPlYCEB84dQ3DMICp4O1rWJbAn0aKuXB+D78LArUgsidAx39qvuFDDbH/x4mw= X-Received: by 2002:a05:600c:4e88:: with SMTP id f8mr55477678wmq.14.1626098035248; Mon, 12 Jul 2021 06:53:55 -0700 (PDT) MIME-Version: 1.0 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> <83v95fabwx.fsf@gnu.org> In-Reply-To: <83v95fabwx.fsf@gnu.org> From: Jonathan Wakely Date: Mon, 12 Jul 2021 14:53:44 +0100 Message-ID: Subject: Re: Benefits of using Sphinx documentation format To: Eli Zaretskii Cc: =?UTF-8?Q?Martin_Li=C5=A1ka?= , "gcc@gcc.gnu.org" , gcc-patches , "Joseph S. Myers" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, KAM_SHORT, RCVD_IN_DNSWL_NONE, 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 13:53:58 -0000 On Mon, 12 Jul 2021 at 14:41, Eli Zaretskii via Gcc wrote= : > > > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > > From: Martin Li=C5=A1ka > > 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 =C2=B6) > > d) internal links are working, e.g. one can easily jump from listin= g of options For me, these items are enough justification to switch away from texinfo, which produces crap HTML pages with crap anchors. You can't find out the anchors without inspecting (and searching) the HTML source. That's utterly stupid. And even after you do that, the anchor is at the wrong place: https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c As somebody who spends a lot of time helping users on the mailing list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo HTML has angered me for many years. Yes, some people like texinfo, but some people also dislike it and there are serious usability problems with the output. I support replacing texinfo with anything that isn't texinfo. > > 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 manual= s and libgccjit) > > 4) support for various output formats, some people are interested in eP= UB 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. This is a problem with texinfo too. > > 5) Lack of macros. > AFAIK, only simple textual substitution is available, no macros > with arguments. Is this a problem for GCC docs though?