This is the mail archive of the
mailing list for the GCC project.
Re: use of sphinx/rest as source for GNAT doc
- From: jose dot marchesi at oracle dot com (Jose E. Marchesi)
- To: Jeff Law <law at redhat dot com>
- Cc: Arnaud Charlet <charlet at adacore dot com>, gcc at gcc dot gnu dot org, karl at freefriends dot org
- Date: Mon, 26 May 2014 18:20:42 +0200
- Subject: Re: use of sphinx/rest as source for GNAT doc
- Authentication-results: sourceware.org; auth=none
- References: <20140523152346 dot GA14154 at adacore dot com> <537F6FC2 dot 2000001 at redhat dot com>
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
Just wondering, what are these long term maintenance problems with
texinfo? Are the texinfo maintainers aware of these problems?