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 D20DD3855023; Mon, 12 Jul 2021 14:13:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D20DD3855023 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1436 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 1m2wgE-0000yZ-2l; Mon, 12 Jul 2021 10:13:06 -0400 Date: Mon, 12 Jul 2021 17:12:57 +0300 Message-Id: <83r1g3aady.fsf@gnu.org> From: Eli Zaretskii To: Jonathan Wakely Cc: mliska@suse.cz, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com In-Reply-To: (message from Jonathan Wakely on Mon, 12 Jul 2021 14:53:44 +0100) 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> <83v95fabwx.fsf@gnu.org> 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, KAM_SHORT, 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@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:13:08 -0000 > From: Jonathan Wakely > Date: Mon, 12 Jul 2021 14:53:44 +0100 > Cc: Martin Liška , > "gcc@gcc.gnu.org" , gcc-patches , > "Joseph S. Myers" > > For me, these items are enough justification to switch away from > texinfo, which produces crap HTML pages with crap anchors. If we want to have a serious discussion with useful conclusions, I suggest to avoid "loaded" terminology. I get it that you dislike the HTML produced by Texinfo, but without some examples of such bad HTML it is impossible to know what exactly do you dislike and why. > You can't find out the anchors without inspecting (and searching) > the HTML source. That's utterly stupid. I don't think I follow: find out the anchors with which means and for what purposes? > And even after you do that, the anchor > is at the wrong place: > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c IME, the anchor is where you put it. If you show me the source of that HTMl, maybe we can have a more useful discussion of the issue. > 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. As somebody who spends a lot of time helping users on every possible forum, and as someone who has wrote a lot of Texinfo, I don't understand what angers you. Please elaborate. > 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. "Anything"? Even plain text? I hope not. See, such "arguments" don't help to have a useful discussion. > > 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. Not for someone who already knows Texinfo. We are talking about switching away of it, so I'm thinking about people who contributed patches for the manual in the past. They already know Texinfo, at least to some extent, and some of them know it very well. > > 5) Lack of macros. > > AFAIK, only simple textual substitution is available, no macros > > with arguments. > > Is this a problem for GCC docs though? I don't know. It could be, even if it isn't now.