Re: gdb and sphinx documentation

[Simon Marchi <simark@simark.ca>]

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