Reconsidering documentation markup

Jim Campbell jwcampbell at
Fri Oct 9 14:04:54 CEST 2009

Hi All,

There are a couple of factors that are leading me to reconsider
rST+Sphinx for the documentation.  They aren't so much shortcomings of
rST+Sphinx so much as how I'm considering the doc's integration with
downstream projects, the larger doc community, and the issue of

If Mallard 1.2 will include a yelp library, and Jannis has indicated
he feels comfortable with the dependencies for the library, I would
rather us be able to use a markup language that is going to be used
across multiple distro projects and will be getting lots of
distro-specific development (and lots of support from other doc
writers) than rST+sphinx, which other distros and other desktop
environments aren't going to be using.

Also, I got feedback from Og Maciel regarding his experience with
Mallard for the Foresight Linux user guide.  He has been able to
author with it pretty easily, and is able to use Transifex for
translations in just the same way that the group was able to use for
Docbook. Seeing as we already have a Transifex installation up and
running, it seems like it would make sense to leverage the
functionality that Transifex provides (not to mention having one
workflow for both UI and documentation translators).

I realize that this is a bit of a switch at this point, but I think
that the ability to handle translations natively and to be using the
same framework as other projects would be best in the long run.

The short-term downside is that the Xfce-doc package would need to be
prepared en-masse in HTML format until a doc reader based on the yelp
library was ready.  Let me know what you think


More information about the Xfce4-dev mailing list