On Thu, 2021-04-01 at 15:30 +0200, Martin Liška wrote: > Hey. > > I've returned to the David's project and I'm willing to finish his > transition effort.
For reference, the original thread about this is in the archives here: https://gcc.gnu.org/pipermail/gcc-patches/2015-November/434055.html > I believe using Sphinx documentation can rapidly improve readability, > both HTML and PDF version, > of various GCC manuals ([1]). Specifically, some of the benefits over the status quo are: - internal hyperlinks in both HTML and PDF output for things like options (see how every reference to e.g. -Wall and -O2 becomes a link to those options, and they themselves have links to the things they encompass) - sane, stable URLs for anchors - syntax highlighting of code snippets (and the format lets us express what language the code snippets are in) - a page splitting structure that makes sense (IMHO) - appropriate use of well-designed CSS The sphinx toolchain is used successfully by numerous projects (e.g. Python, the Linux kernel, and LLVM). > I've spent some time working on the David's texi2rsf conversion tool > ([2]) > and I'm presenting a result that is not perfect, but can be > acceptable after a reasonable > amount of manual modifications. I think some further tweaking of the conversion script is needed first; I'd rather iron out the script rather than play whack-a-mole manually. I enjoy proofreading conversions, but I'm trying to focus right now on analyzer bugfixing for GCC 11. > So far I focused on the 2 biggest manuals we have: > > (1) User documentation > https://splichal.eu/sphinx/ > https://splichal.eu/sphinx/gcc.pdf > > (2) GCC Internals Manual > https://splichal.eu/sphinx-internal > https://splichal.eu/sphinx-internal/gccint.pdf > > I'm aware of missing pieces (thanks Joseph) and I'm willing to finish > it. One important requirement is manpage output. Sphinx can do that - what does the output look like based on the texi2rst output? > That said, I'm asking the GCC community for a green light before I > invest > more time on it? +1 from me, but you probably guessed that :) Dave > Cheers, > Martin > > [1] https://gcc.gnu.org/onlinedocs/ > [2] https://github.com/davidmalcolm/texi2rst >
