gdb and sphinx documentation

gdb and sphinx documentation

[Tom de Vries via Gdb-patches]

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

Re: gdb and sphinx documentation

[Gaius Mulley via Gdb-patches]

Tom de Vries via Gdb-patches <gdb-patches@sourceware.org> writes:

> Please take a look if you're interested ( https://splichal.eu/tmp/gdb ).

looks great!

Re: gdb and sphinx documentation

[Eli Zaretskii via Gdb-patches]

> Date: Sun, 18 Sep 2022 10:31:43 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>
> From: Tom de Vries <tdevries@suse.de>
> 
> 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 ).

I also suggest to become familiar with the long discussion of this on
the GCC list:

  https://gcc.gnu.org/pipermail/gcc/2021-June/236172.html
  https://gcc.gnu.org/pipermail/gcc/2021-June/236604.html
  https://gcc.gnu.org/pipermail/gcc/2021-July/236638.html
  https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html

and with the POV of the Texinfo maintainer:

  https://gcc.gnu.org/pipermail/gcc/2021-July/236756.html

From my side, I can just say that if GDB decides to migrate to Sphinx,
I will step down as the person responsible for the GDB documentation,
because it's too late for me to learn yet another incompatible
documentation system (and insufficiently documented on top of that).

Re: gdb and sphinx documentation

[Simon Marchi via Gdb-patches]

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

Re: gdb and sphinx documentation

[Joel Brobecker via 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