On Wed, 29 Oct 2008 00:36:44 +1100 "Trent W. Buck" <[EMAIL PROTECTED]> 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 _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
