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 0A5453855023; Mon, 12 Jul 2021 14:30:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 0A5453855023 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 E478321E39; Mon, 12 Jul 2021 14:30:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1626100223; 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=OAtaWi39oGSBYOCOnv50wHr6SvFZjgF9/OjCyIGE+v4=; b=x/Pq+rvIROs+D2my7XhfCAvNgNslKY7a2GD8U+01mBlsQq1uUA3h5W9OjpHEcCFk807uum sHANPzzitgVolUM4J+PxCSLYb4hA5+c3L8W3cp53ZHoxrt2sMmsZPmLFZvpbM4OCGK6L7J Tj45ogyrlkR/vr4FzDluXFIB8BFZdyU= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1626100223; 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=OAtaWi39oGSBYOCOnv50wHr6SvFZjgF9/OjCyIGE+v4=; b=5h325m+05Eo3pXkQ3G+1xLVJez86470CSajQWaf+ESxuzAin05yt9Y4AMF6cTOvJ7Jfhf5 l1Jj/wX+gTcBuhBw== 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 C473013BAF; Mon, 12 Jul 2021 14:30:23 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id yLX0Lv9R7GDzfAAAMHmgww (envelope-from ); Mon, 12 Jul 2021 14:30:23 +0000 Subject: Re: Benefits of using Sphinx documentation format To: Eli Zaretskii , Jonathan Wakely Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com References: <1446990946.2994.192.camel@surprise> <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> <83r1g3aady.fsf@gnu.org> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <144d27f7-9486-0515-2ebd-4e8d9d9fc3b2@suse.cz> Date: Mon, 12 Jul 2021 16:30:23 +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: <83r1g3aady.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, KAM_SHORT, 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:30:26 -0000 On 7/12/21 4:12 PM, Eli Zaretskii wrote: >> 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. Please follow my 1) from Benefits and *read* bullet points a) to f). That will give you an answer. > >> 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? Benefits, 1c). > >> 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. Problem is that Texinfo emits poor HTML where # link points to a wrong place. Open the given page, view source and search for
. > >> 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. You can't point to an option documentation. > >> 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. Yes, people will have to learn a new syntax. Similarly to transition of SVN, people also had to learn with a more modern tool. > >>> 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. Then it's not an argument, sorry. Martin