public inbox for gdb-patches@sourceware.org
 help / color / mirror / Atom feed
* gdb and sphinx documentation
@ 2022-09-18  8:31 Tom de Vries
  2022-09-18 13:06 ` Gaius Mulley
                   ` (2 more replies)
  0 siblings, 3 replies; 5+ messages in thread
From: Tom de Vries @ 2022-09-18  8:31 UTC (permalink / raw)
  To: 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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: gdb and sphinx documentation
  2022-09-18  8:31 gdb and sphinx documentation Tom de Vries
@ 2022-09-18 13:06 ` Gaius Mulley
  2022-09-18 13:20 ` Eli Zaretskii
  2022-09-18 22:25 ` Simon Marchi
  2 siblings, 0 replies; 5+ messages in thread
From: Gaius Mulley @ 2022-09-18 13:06 UTC (permalink / raw)
  To: Tom de Vries via Gdb-patches; +Cc: Tom de Vries

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!

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: gdb and sphinx documentation
  2022-09-18  8:31 gdb and sphinx documentation Tom de Vries
  2022-09-18 13:06 ` Gaius Mulley
@ 2022-09-18 13:20 ` Eli Zaretskii
  2022-09-18 22:25 ` Simon Marchi
  2 siblings, 0 replies; 5+ messages in thread
From: Eli Zaretskii @ 2022-09-18 13:20 UTC (permalink / raw)
  To: Tom de Vries; +Cc: 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).

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: gdb and sphinx documentation
  2022-09-18  8:31 gdb and sphinx documentation 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
  2 siblings, 1 reply; 5+ messages in thread
From: Simon Marchi @ 2022-09-18 22:25 UTC (permalink / raw)
  To: Tom de Vries, 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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: gdb and sphinx documentation
  2022-09-18 22:25 ` Simon Marchi
@ 2022-09-26  0:03   ` Joel Brobecker
  0 siblings, 0 replies; 5+ messages in thread
From: Joel Brobecker @ 2022-09-26  0:03 UTC (permalink / raw)
  To: Simon Marchi via Gdb-patches; +Cc: Tom de Vries, 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

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-09-26  0:03 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-09-18  8:31 gdb and sphinx documentation 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 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).