It turns out that while the current output from "darcs --help" is
well-formed reST, it is not marked up quite correctly -- resulting in
ugly output.

Darcs help's output needs to be changed so as to be marked up well for
reST.  If people think the reST output is too ugly, we need instead to
continue down the preproc.hs route and have two versions of show() for
darcs commands -- one for TeX (now reST) and one for humans.

Here is the original reply from the rst2pdf maintainer:

On Mon, Nov 10, 2008 at 11:11:12AM -0200, Roberto Alsina wrote:
> Trent W. Buck writes:
>> Hi, see attached example.  It looks really ugly.
>
> I took a careful look today and I think your option lists are not
> correctly written.
>
> If you check the restructured text spec, when there are multiple
> options in a line, you need to separate them using ", " and you have
> multiple spaces. [...]  Also, option lists are not supposed to be
> indented, or they are interpreted as being inside a block quote.
>
> I think the html writer is producing a "nice" output mostly by
> coincidence :-)

Because Cabal cannot (currently) build intermediary binaries without then
installing them, src/darcsman.hs probably also needs to be subsumed into
the main darcs binary, so e.g. darcs --help-man or darcs help --man would
emit the manpage.

This being the case, it is probably reasonable to have three output formats:
darcs help emits human-readable help, darcs help --roff emits a manpage and
darcs help command --rest emits help for a command in slightly different reST
format.  If it's preferred, we could call the options --manpage and --user-manual
instead.

Hi Trent, now that we have things like darcs help manpage, is it time to
wake this bug up?