* 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).