On Sun, 8 Nov 2015, David Malcolm wrote: > I've been experimenting with using Sphinx [1] for GCC's documentation. > > You can see an HTML sample of GCC docs built with Sphinx here: > https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html > (it's a work-in-progress; i.e. there are bugs).
Observations: * Could you provide the PDF version there as well? * The option summary <https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/option-summary.html> seems a complete mess. * The indexes are missing. > It doesn't *quite* do a direct .texi to .rst conversion yet: it can take > the XML output from texinfo's "makeinfo --xml", and generate either one > big .rst file, or a group of smaller .rst files. > > My hope was that for every gcc/docs/foo.texi file we have, my tool would > be able to generate a gcc/docs/foo.rst (maybe retaining the name, to > allow for sane diff and hence sane patch review). > > Unfortunately, "makeinfo --xml" resolves includes and conditional > processing, so the underlying input structure of .texinfo files is lost > at that point. > > To fix that, I've been working on a frontend from texi2rst that > re-implements the .texi to xml processing, retaining information on > includes, and directives, so that I can translate them to > corresponding .rst directives. Unfortunately it's clear that I'm not > going to finish that before stage 1 closes - but I think it's feasible > in the stage3 timeframe. You do of course need to convert documentation fragments in target.def in-place and adapt genhooks (preserving the arrangements of both tm.rst.in and tm.rst being checked in, or some other such arrangement that ensures there are always both GPL and GFDL copies of the hook documentation checked in, with genhooks dealing with keeping them in sync). Other things to consider: preserving comments (where applicable); preserving @ignore contents (where the function is to comment out text); keeping manpage generation (which currently uses @c man comments together with @ignore) working; keeping --with-pkgversion and --with-bugurl working; keeping the principle that BASE-VER is the only checked-in file with the version number and everything else gets the version number at build time; dealing with the INTERNALS conditionals in files used in multiple manuals (and some others such as cppmanual conditionals). -- Joseph S. Myers jos...@codesourcery.com
