public inbox for gdb-patches@sourceware.org
 help / color / mirror / Atom feed
From: Joel Brobecker <brobecker@adacore.com>
To: Simon Marchi via Gdb-patches <gdb-patches@sourceware.org>
Cc: Tom de Vries <tdevries@suse.de>, Joel Brobecker <brobecker@adacore.com>
Subject: Re: gdb and sphinx documentation
Date: Sun, 25 Sep 2022 17:03:55 -0700	[thread overview]
Message-ID: <YzDsayEhC9v4PEMJ@adacore.com> (raw)
In-Reply-To: <682c026e-e7c9-054b-4106-d8e83769bb00@simark.ca>

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

      reply	other threads:[~2022-09-26  0:03 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-09-18  8:31 Tom de Vries
2022-09-18 13:06 ` Gaius Mulley
2022-09-18 13:20 ` Eli Zaretskii
2022-09-18 22:25 ` Simon Marchi
2022-09-26  0:03   ` Joel Brobecker [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YzDsayEhC9v4PEMJ@adacore.com \
    --to=brobecker@adacore.com \
    --cc=gdb-patches@sourceware.org \
    --cc=tdevries@suse.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).