This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: use of sphinx/rest as source for GNAT doc


On 05/23/14 09:23, Arnaud Charlet wrote:
At AdaCore, we have switched most of our product documentation the
rest/sphinx format: http://sphinx-doc.org/
which provides most of the advantages of texinfo (text format,
can generate output in multiple formats, supported by free software), as well
as additional advantages, at least for us (more modern output, actively
maintained, support more output formats, simpler syntax).

So we are investigating converting also the GNAT documentation
(GNAT User's Guide and GNAT RM) to this format.

I understand that GCC as whole likely wants to stick with texinfo
for the time being, so I'm not really suggesting a switch here, but
what about the following approach:

- the GNAT doc source would be in rest format (.rst files) instead
   of texinfo (.texi files)
- we would still provide .texi files, generated automatically by the
   sphinx toolset (via 'make texinfo') and committed in the repository
   (similarly to configure vs configure.in/aclocal.m4), so end users
   would not have any extra dependency, and generation of documentation
   would still be possible from the .texi files directly

What do people think in principle about the above proposal?
Would that be an acceptable move for the GCC project?
Given the long term maintenance issues around texlive/texinfo, investigation of other formats is wise. The fact that sphinx can generate .texi files is a huge win from a flexibility standpoint.

I'd support this as a pilot for converting the entire project. The generated .texi files should have some kind of comment marker indicating they are generated from the .rst files and how to recreate them so that other maintainers can DTRT with the Ada docs as necessary.



Jeff



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]