On Mon, 2015-11-09 at 16:37 -0700, Sandra Loosemore wrote: > On 11/08/2015 06:55 AM, David Malcolm wrote: > > I've been experimenting with using Sphinx [1] for GCC's documentation. > > > > [snip] > > > > The primary advantages of .rst/sphinx over .texi/texinfo I see are in > > the generated HTML: > > > > * sane, stable URLs (so e.g. there is a reliable URL for the docs for, > > say, "-Wall"). > > > > * a page-splitting structure that make sense, to me, at least [3] > > > > * much more use of markup, with restrained and well-chosen CSS > > (texinfo's HTML seems to ignore much of the inline markup in > > the .texinfo file) > > > > * autogenerated internal links, so that almost everything is clickable, > > and will take you somewhere sane, by default > > > > * syntax-highlighting of code examples, with support for multiple > > programming languages (note the mixture of C, C++, Fortran, etc in the > > docs for the gcc options). > > > > * looks modern and fresh (IMHO), letting casual observers see that the > > project is alive and kicking. > > > > > > Thoughts? > > If we're going to switch documentation formats, I'd rather we used > DocBook. I've had to use "restructured text" before and found it really > awkward.
My own preference is the opposite; I've used DocBook and rst, and I find DocBook to be the awkward one [1]. I think DocBook may be OK as an interchange format, but I find it overly verbose to author and to read in plain-text form. (I'm not so fond of some parts of .rst's inline markup syntax, but I find its structural aspects to be extremely expressive and concise; overall I find it a joy to work with). > But, personal preferences aside, I also think it's more important that > we commit documentation-person resources to making the content more > correct, readable, and better organized, than to making the HTML output > look "modern and fresh", or worse yet, translating the docs to another > format and having to proofread them for conversion goofs. Correct, readable and well-organized documentation are laudable goals... but I think that, to a first approximation, we're already there: I just feel that the content is hidden behind a poor tool chain. I believe that no matter how good we make the .texi files, the issues with URLs, HTML page-splitting, etc with how texinfo's HTML generation works will hold gcc back. > BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for > the generated manuals, to make them a little "prettier". Maybe > something like that would go a long way towards solving the perceived > problems here? I'm interested in seeing that, though presumably the URL and page-splitting issues would remain (is this at the CSS level, or do you make deeper changes to the HTML generation?) > Or improvements to texinfo's HTML generation. texinfo is implemented in Perl, and FWIW, for me to help, that's a showstopper (sprry; I've tried several times to get my head around Perl, but my brain seems incompatible with it). One other approach might be to retain .texi as the canonical format, but have a optional custom HTML generator (perhaps using texi2rst to generate .rst for sphinx, this time as an intermediate step during "make html", rather than as a one-time conversion). The main thing I think it's missing is a way to express the language of embedded source examples, so that they can be syntax-highlighted. Thanks; I hope this is constructive. Dave [1] fwiw, my opinion on this has changed; a decade or so ago I worked on a DocBook editor, http://conglomerate.org/
