[darcs-users] Darcs Manual

[Trent W. Buck]

On Tue, Jul 21, 2009 at 11:20:27PM -0400, Max Battcher wrote:
> I know you had some issues with Sphinx the last few times it was
> discussed, but I do think several of them are on the way to being
> closed and I also think that using an existing, tested documentation
> build tool should help more than trying to ad hoc rebuild it in
> haskell/pandoc. (Or maybe even just as a "today" solution until such
> a haskell-based equivalent is built.)

I agree that Sphinx produces the best HTML output.  I've got no
problem with adopting Sphinx for building an HTML user manual.

*My* immediate goal re restization is:

 - comprehensive command/file/environment docstrings
   (command_description) in the source code marked up as reST.

 - Rendering these as plain text when the user runs "darcs help foo"
   without relying on external commands.  I don't want users seeing
   double colons before verbatim blocks or underscores peppering their
   display when they as for "darcs help push".

To me, that basically means pandoc is already a necessary dependency
for "darcs help".  It seems straightforward to me to make "darcs help
manpage" use pandoc instead of emitting reST and having cabal pipe it
through an rst2man (which is not yet a stable part of docutils), but
I'm not married to that idea.

My main concerns with Sphinx are that its PDF output requires LaTeX to
build and looks like a fugly TeX document (admittedly subjective) and
that it requires non-standard ToC and include directives that break
OTHER reST parsers (i.e. we'd be "locked in" to only using Sphinx).

But since I've demonstrably been too busy with "darcs help" and the
manpage to give the user manual any love, I'm prepared to let you run
with Sphinx and worry about possible fallout in the future.

PS: I also have concerns about pandoc's incomplete reST parser, but
I stopped caring about that, too :-)