From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 From: Joel Brobecker To: Simon Marchi via Gdb-patches Cc: Tom de Vries , Joel Brobecker 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-Spam-Status: No, score=-4.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, 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: Mon, 26 Sep 2022 00:04:00 -0000 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