From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id 2shfLoXsMGNsBAAAWB0awg (envelope-from ) for ; Sun, 25 Sep 2022 20:04:21 -0400 Received: by simark.ca (Postfix, from userid 112) id B00821E112; Sun, 25 Sep 2022 20:04:21 -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=R+oAVmCE; 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=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RDNS_DYNAMIC,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from sourceware.org (ip-8-43-85-97.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 541D81E0D5 for ; Sun, 25 Sep 2022 20:04:21 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 7A2193858437 for ; Mon, 26 Sep 2022 00:04:20 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7A2193858437 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1664150660; bh=TfuAlL8uARenukcbiUDF0NSlEaCkq5iGjADjATkYL64=; h=Date:To:Subject:References:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=R+oAVmCE3lpjbedB6/FxHAlCKjeYEnH9yFZQUhdJtUaZts6UBpUSVHiDUw1WaRn7P c8UmDTloVCct7T9VRGKJhfq7Ixix6HQGzMwDfQck7IZ7KtZECariQ5it/WadSGz50C oyQOAk/YHkaBmvlDAC3t9Ghn9rtX4toYC8/qDUpU= Received: from mail-pl1-x62a.google.com (mail-pl1-x62a.google.com [IPv6:2607:f8b0:4864:20::62a]) by sourceware.org (Postfix) with ESMTPS id DF4523858CDA for ; Mon, 26 Sep 2022 00:03:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org DF4523858CDA Received: by mail-pl1-x62a.google.com with SMTP id w20so4737821ply.12 for ; Sun, 25 Sep 2022 17:03:58 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date; bh=TfuAlL8uARenukcbiUDF0NSlEaCkq5iGjADjATkYL64=; b=T3KbrT8gtBlinL5g9Nc4g4LWwL77dX0X2MbAQU3iuM+eNCIR7d0qVb3BuXCxIiSdvS akTRK3/f82q7sRARf8JPrHWNCUmJCWIGeSV+kTBvvmP5TEXxBVUJZsrwzioqnG+YxjXL My1wuTywr/UZs0qYfcF6gcAe5dVgLRfJOc87sLYJVRwWjG7gvI3EnNMkjn7fj5f0ktU4 HcBGZ1aGaIQFHHzLY32+fMjzosum3etJz+OuS8w4Sz9GeL+qDkcJFmyLYQ3eLz3sLzrL vPYZ9LT2VrTmKkcPFI+1sEGG8aNnCXbx6yibLZIQ6k8YwV/jYvp/uVGNabOLjaDgFaIc EUzw== X-Gm-Message-State: ACrzQf3cSqCEyvw/wqof7HtfBdfJfVSWtcgU7Ts456Hm7eFEzkB/9mRX 5j+I4A7m+kMTbirLT0I8rv1r X-Google-Smtp-Source: AMsMyM6d6sUODcCAQvKZrWf03I89G7VQxlZnwlDXx+wrMkVrQp1gmW5885iI+SChwP63f6p6JmccZg== X-Received: by 2002:a17:90b:1c10:b0:202:b515:2d0f with SMTP id oc16-20020a17090b1c1000b00202b5152d0fmr22374001pjb.111.1664150637915; Sun, 25 Sep 2022 17:03:57 -0700 (PDT) Received: from takamaka.gnat.com ([184.69.131.86]) by smtp.gmail.com with ESMTPSA id h13-20020a170902f54d00b0016dbaf3ff2esm9823872plf.22.2022.09.25.17.03.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 25 Sep 2022 17:03:56 -0700 (PDT) Received: by takamaka.gnat.com (Postfix, from userid 1000) id AE63780164; Sun, 25 Sep 2022 17:03:55 -0700 (PDT) Date: Sun, 25 Sep 2022 17:03:55 -0700 To: Simon Marchi via Gdb-patches Subject: Re: gdb and sphinx documentation Message-ID: References: <682c026e-e7c9-054b-4106-d8e83769bb00@simark.ca> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <682c026e-e7c9-054b-4106-d8e83769bb00@simark.ca> 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: Joel Brobecker via Gdb-patches Reply-To: Joel Brobecker Cc: Tom de Vries , Joel Brobecker Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" Hello, > 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. I think it would be useful to state what the objectives of the migration would be, as this is not quite clear to me. For instance, is it about getting a different rendering (in HTML? in PDF?), or is it about adopting a technology with specific benefits? Once we understand the objectives, we can perhaps discuss what other options there are to meet those goals, and decide whether Sphinx is the best way forward. In particular, maybe there is a way to get better rendering at a small cost while keeping texinfo? (I do not have a particular attachment to texinfo, fwiw) -- Joel