From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca (simark.ca [158.69.221.121]) by sourceware.org (Postfix) with ESMTPS id D24F53858C54 for ; Sun, 18 Sep 2022 22:25:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D24F53858C54 Received: from [192.168.11.206] (unknown [185.156.120.200]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by simark.ca (Postfix) with ESMTPSA id E21671E0D5; Sun, 18 Sep 2022 18:25:57 -0400 (EDT) Message-ID: <682c026e-e7c9-054b-4106-d8e83769bb00@simark.ca> Date: Sun, 18 Sep 2022 18:25:54 -0400 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.0 Subject: Re: gdb and sphinx documentation Content-Language: fr To: Tom de Vries , "gdb-patches@sourceware.org" References: From: Simon Marchi In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-7.2 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, NICE_REPLY_A, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 18 Sep 2022 22:26:00 -0000 On 9/18/22 04:31, Tom de Vries via Gdb-patches wrote: > Hi, > > at the GNU Cauldron, Martin Liška presented a BOF about migrating GCC documentation to sphinx format ( https://gcc.gnu.org/wiki/cauldron2022#cauldron2022talks.the_sphinx_documentation_bof ). > > I asked him about the gdb documentation, and he ran the migration scripts he used for gcc on it.  The result is obviously a bit rough, but gives a nice idea what it could look like. > > Please take a look if you're interested ( https://splichal.eu/tmp/gdb ). > > Thanks, > - Tom Hi Tom, At first glance, it looks great. When digging into it, though, you see a lot of small buglets and inconsistencies that would need to be fixed manually. One thing that strikes me is: why is "Tracepoints" the first section? On the home page, there is some kind of table of contents (where "Tracepoints" is first) and when you go down a bit there's another, more complete. What I like the most about the Sphinx output is the style of it. I think I prefer the sans-serif font it uses, vs the serif font used in the current manual. The content width is limited to something reasonable instead of taking the whole browser window, so it's less horizontal eye movement (I can make my browser window smaller to achieve the same thing but it's nice if it's like that by default). The commands or other text that is in a monospace font has this light grey background or border that makes it easy to visually separate from the rest of the text. Since it's possible to style the texinfo HTML output using CSS, I think I would already be very happy to see the current manual's html output get a fresh look. Simon