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.
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.
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? Or improvements to texinfo's HTML generation.
-Sandra
