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

[Peter Arrenbrecht]

On Fri, Jun 12, 2009 at 3:24 AM, Matt Mackall<mpm at selenic.com> wrote:
> On Thu, 2009-06-11 at 13:49 -0400, Greg Ward wrote:
>> On Thu, Jun 11, 2009 at 1:40 PM, Matt Mackall<mpm at selenic.com> wrote:
>> > 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 fundamental strength *and weakness* of reST is that it does have
>> rigorously defined behaviour.  It's got a grammar and everything.
>
> I guess I wasn't clear. The problem is not any weakness in the grammar,
> the problem is that there's no clear delineation between text and
> formatting. Compare XML, HTML, TeX, etc. This is both a requirement (we
> want to have readable doc source) and a failure (we don't want to mangle
> our sources to work around formatter escaping surprises).
>
> 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. And my
> contention is that's going to be true unless we either:
>
> 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.

Maybe we could live with our own formatter (or pre-formatter) that
handles our everyday needs in plain ASCII and use an escape hatch for
the rest? We would have markup that says: this is the plain text
version of this bit, and this is the one with bells and whistles. So
the chosen formatter would only have to handle our everyday formatting
needs from a single source.

Something like (never mind the actual markup I use here):

[[xhtml]]
<img src="..."/>
[[plaintext]]
a - b - c
  \ d
[[continue]]

Of course, our plaintext (pre-)formatter could be a standard one, or a
subset thereof.

In any case, I think we should avoid inline formatting that needs to
be stripped for plaintext, because then we would have to rewrap the
plaintext lines. Getting this right the way the author intended is
likely not trivial.

So I'd say we should only have markup that spans entire lines, or
affects only lines that one does not rewrap anyway (like prefixes for
headers).

-parren