[darcs-users] Sphinx or reST (for user manual)?

Mark Stosberg mark at summersault.com
Tue Oct 28 14:04:33 UTC 2008


On Wed, 29 Oct 2008 00:36:44 +1100
"Trent W. Buck" <trentbuck at gmail.com> wrote:

> I'm unilaterally moving this thread onto the mailing list because I
> want to give any pro-Sphinx lurkers a fair chance to respond, and
> because I want my rationale on record.
> 
> For those who have just joined us: Mark, Max and I have been working
> on overhauling the user manual infrastructure as a prelude to doing
> some serious copy editing, with the intention of increasing its
> accessibility (more output formats), readability (that's the copy
> editing) and maintainability (by switching from TeX to a lightweight
> markup language).
> 
> So far, I've done some bulk (read: buggy) translation of src/*.tex to
> restructured text (reST).  I posted the rendered output to the list
> earlier this week.
> 
>     darcs get http://code.haskell.org/darcs/user-manual
> 
> Max then made some minor changes to demonstrate Sphinx, an extension
> of reST that addresses some large-document issues with plain reST.
> 
>     darcs get http://repos.worldmaker.net/darcs/sphinx/
> 
> I've now had a chance to evaluate Sphinx for our user manual, and
> below I make a case for sticking with plain reST, at least in the
> short term.

Thanks for researching thinking this through through. 

I will highlight just one point:  Sphinx builds on reST. So by choosing
reST now, we are heading the direction of Sphinx, so they aren't really
conflicting or competing goals.

I'm nearly always a fan of starting with a simpler solution and working towards more 
complex. So, trying reST for now makes sense to me. If we find that
it's not working well enough, we know that Sphinx is there as a fairly
easy option to explore later.

    Mark




More information about the darcs-users mailing list