From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id UedxGAubJ2OdJDwAWB0awg (envelope-from ) for ; Sun, 18 Sep 2022 18:26:19 -0400 Received: by simark.ca (Postfix, from userid 112) id 532591E112; Sun, 18 Sep 2022 18:26:19 -0400 (EDT) Authentication-Results: simark.ca; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=FP5Y0sLi; dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-4.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,NICE_REPLY_A,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 62A6D1E0D5 for ; Sun, 18 Sep 2022 18:26:18 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id CD26B3858C55 for ; Sun, 18 Sep 2022 22:26:17 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org CD26B3858C55 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1663539977; bh=T1NkCnkEkaMauIAgpbG0lc/I7Jr2LNCcmBFjvD7WXoc=; h=Date:Subject:To:References:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=FP5Y0sLienkmJvrAMFq0NAlYqs3pul0lLuvhh6evc63SDD9m4Cb72pdns3dgV5xaB jM0HPfyB+rvGlVvLxtIyqTgNhLVxr3QIctXeqIp2qqPCUiwGdrb6JqZrUvGtXbbviD u1rJxMGeNLH77K/XqcvFf1k3MfWvn4Uh7RPObNdw= 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: In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: , From: Simon Marchi via Gdb-patches Reply-To: Simon Marchi Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" 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