On 4/2/21 5:40 PM, Martin Sebor wrote: > On 4/1/21 7:30 AM, Martin Liška wrote: >> Hey. >> >> I've returned to the David's project and I'm willing to finish his >> transition effort. >> I believe using Sphinx documentation can rapidly improve readability, both >> HTML and PDF version, >> of various GCC manuals ([1]). 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. >> >> 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. >> >> That said, I'm asking the GCC community for a green light before I invest >> more time on it?
Hello. > > I like the output quite a bit, especially that things like option > references are automagically linked to their documentation. I spent > just a bit of time looking through the HTML and PDF above and found > a few minor issues. I suspect they're due to the conversion script > not being finished yet but just to confirm please see below. Exactly, the script is supposed to do 99% of the transition automatically, the rest needs a manual intervention. > > Is the source we'd work with the same as what shows up when I click > the 'View page source' link? (Or is there some preprocessing involved?) Yes, it's the source as is. > > I'm not excited about changing tools. I like that Texinfo is a GNU > project; AFACT, Sphinx is not. I don't any particular benefit. As already mentioned, Sphinx is a open-source project with rich history and broad collection of projects using it: https://www.sphinx-doc.org/en/master/examples.html > In the original thread David linked > to there was a suggestion to use Texinfo and Sphinx side by side. > I.e., keep .texi as the master source format and generate the .rst > files using the conversion script on demand. Would making that > the first step of the transition be a viable option? (With the idea > of giving it a try and deciding whether to convert after some time?) I've just set up a pipeline that can generate all the manuals from texi file: https://splichal.eu/gccsphinx/ However, the generated .rst files will need a manual changes before we can use it as a replacement. So once we make a decision, .texi files will be left after the transition. Note it's very difficult to write a 1:1 conversion tool from TEXI to RST. > > Martin > > [*] The linking doesn't always seem to work (e.g., > :option:`-fabi-version=4` under -Wabi). I'm guessing it's not yet > done in the conversion script (or there's no -fabi-version=4 in > the index) and not a Sphinx limitation. Should be fixed now, one needs to split the '=4' part out of :option: directibe. > > It doesn't add links for attributes but presumably that could also > be made to happen in the conversion, right? I partially added that. > > It doesn't seem to preserve newlines in long lists of options (like > under -Wall), so the result is just one long running series of options > that's hard (for me) to follow. Presumably there's a way to do that > too (add a newline after each :option?) That's not desired and it's up to builder (PDF, HTML, ...) how the options should be formatted. > > It mentions both the positive and the negative forms of options as > headings (like -Wmain, -Wno-main). That seems superflous and, with > very long option names (I noticed this for example with > -Wno-analyzer-use-of-pointer-in-stale-stack-frame) the heading in > the PDF can run off the right edge of the page. But based on > the source it also looks like it should be easy to adjust in > the conversion script if we wanted to keep just one form, right? Yes. I updated the script to split the lines when we reach a long list of options. Note that we likely want to preserve both position and negative options because of references and in order to express what is default. I've created a version 2 that contains various manuals (and man pages): https://splichal.eu/gccsphinx/ Martin > > >> >> Cheers, >> Martin >> >> [1] https://gcc.gnu.org/onlinedocs/ >> [2] https://github.com/davidmalcolm/texi2rst >> >
