gdb and sphinx documentation

[Joel Brobecker]

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