[PATCH] hgrc5: wrap corrected text at 80 chars for manpage

[Martin Geisler]

On Fri, Jun 12, 2009 at 03:24, Matt Mackall<mpm at selenic.com> wrote:

> It's important to note that Mercurial's -source- for manpage generation
> is also -final output- for online help. And the online help looking good
> is actually more important than the manpage looking good. That means
> that various grotesque things that you might want to do in asciidoc or
> reST to achieve some formatting end are simply not acceptable.

I agree and this is where the difference between asciidoc and reST
shows: our docstrings are currently not valid asciidoc input (or
rather, the dancing bear accepts it, but the output is not as
intented). I haven't tested it yet, but I believe that the docstrings
would fare much better with reST, without being changed.

> a) write our own docstring to manpage formatter tailored to our precise
> needs
>
> or
>
> b) reformat our docstrings for online help using some formatter that is
> simple enough to ship with hg
>
> I'm beginning to lean towards (b). Which means we need something that
> can take nearly-plain-text input and generate plain text, manpage, and
> HTML output. We've discussed adding some minimal markup for short vs
> long help.

I would much prefer to use a standard format like reST instead of
inventing our own.

We currently use a very small subset of asciidoc in the docstrings,
and we're even using it wrong. I suggest that we use a similarly small
subset of reST, but this time use it correctly :-)

The built-in help can then massage the docstrings lightly like Bazaar
does in order to make them even more plain text than they already are.

-- 
Martin Geisler