[darcs-users] Darcs Manual

[Max Battcher]

Trent W. Buck wrote:
> 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.

I do think that is a reasonable approach to use pandoc for help/man.

> 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).

There is an addon in testing to do rst2pdf/reportlab PDF builds for 
Sphinx now. The test output I've seen so far looks pretty nice and the 
addon maintainer's goals are to get the PDF output to look as close the 
HTML output as possible (while respecting the way a PDF should look as 
well).

I've been meaning to test this addon with some of my own Sphinx builds, 
and I'd be interested in testing it with Darcs' documentation as well.

As for the "non-standard" directives, I don't think it would result in 
"lock in". ReST was designed for "extension" directives and 
theoretically other reST parsers should allow for extension plugins to 
support new directives. I'm guessing that directive plugins aren't part 
of the subset of reST that pandoc supports, but docutils itself has 
"always" supported it. (Sphinx' directives are in fact just docutils 
plugins and "theoretically" could be extracted from Sphinx, although 
that is probably more work than is useful.)

Worst case, the reST using those directives won't work and will need to 
be rewritten and I don't think that will be a horrible problem. Beyond 
that, Sphinx provides several methods to export its information 
(particularly the ToC information) and could be bent to a semi-automated 
conversion _should_ the need arise. (The JSON-serialized build alone is 
actually surprisingly useful.)

--
--Max Battcher--
http://worldmaker.net