From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) by sourceware.org (Postfix) with ESMTPS id E1BDF385801A; Mon, 12 Jul 2021 13:25:49 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org E1BDF385801A 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-out2.suse.de (Postfix) with ESMTPS id C57B61FF97; Mon, 12 Jul 2021 13:25:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1626096348; 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=NL4W9SEmNaWILpmbKgHMz8NM8Svba9DgD0LR7LqzRSc=; b=jAu+xGLjEWXplziN8DqbY5CUvSGJOpDCb10Kh1WnDFlsmSbVPvMO79TnDuGD0vVuiR120B ER4LIGI2JVPlgt0kVKu4yaT4sfqzgmOHv6QV568rruY7+BVFROpdsuktmomu93R0Gte2pv 8OSvue6l9BuVQIFeaAdpPWiBywArCtY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1626096348; 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=NL4W9SEmNaWILpmbKgHMz8NM8Svba9DgD0LR7LqzRSc=; b=/jkyUMfjUQaZi7FosjhXtBvQfiofhTrrnnebx6RHUWJyRRo5lfb82JrhuHr0/Z3KKTIIhE vRju2UwJUTdkmwCg== 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 6A0F613BA8; Mon, 12 Jul 2021 13:25:48 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id WZXwGNxC7GAbaAAAMHmgww (envelope-from ); Mon, 12 Jul 2021 13:25:48 +0000 Subject: Benefits of using Sphinx documentation format To: Hans-Peter Nilsson , Eli Zaretskii Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com 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> From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Message-ID: <98388e12-3712-575b-9387-45b6ea7ef498@suse.cz> Date: Mon, 12 Jul 2021 15:25:47 +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: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, 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, 12 Jul 2021 13:25:52 -0000 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]): 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 ΒΆ) 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] 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 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). 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