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

[Matt Mackall]

On Thu, 2009-06-11 at 11:29 +0200, Martin Geisler wrote:
> Matt Mackall <mpm at selenic.com> writes:
> 
> > As I suggested last time this came up, it might be time to reconsider
> > our use of asciidoc. Our formatting needs here are fairly minimal.
> > It'd probably be pretty easy for gendoc.py to generate decent nroff
> > output directly.
> 
> What do you think of reStructuredText?

I think we'll probably find that it has all the same failings as
asciidoc. The fundamental strength _and weakness_ of asciidoc is that it
does not have a rigorously defined behavior. This means that you can
often take something that looks reasonable in plain text and reformat it
into something that looks reasonable in a man page or HTML. That's
great.

The problem with this is, the set of things that look fine as plain text
-and- convert well will always be significantly smaller than the set of
things that look fine in plain text but don't convert well for a given
set of conversion rules. Will a given translator get confused by the '.'
in '.hgrc' or the '*' in 'hg add *' or the '[' in 'hg log [-r REV]'? It
will almost certainly fall afoul of something.

Unless, of course, -we- control the conversion rules and tailor it to
the precise needs of our documentation.

The alternative is to give up on plain text source docs and generate hg
help output from marked-up docstrings. But I'm not keen on adding a
dependency for help, so we'd probably still end up writing our own
converter.

-- 
http://selenic.com : development and support for Mercurial and Linux