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

Martin Geisler mg at lazybytes.net
Thu Jun 11 04:29:39 CDT 2009


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 it has a much better
syntax than asciidoc, but it's manpage support looks a bit experimental.
There is a rst2man command, but I don't think it has been released:

  http://docutils.sourceforge.net/sandbox/manpage-writer/

It is in Debian Unstable, though, so maybe it's good enough:

  http://packages.debian.org/unstable/main/rst2man

I'm thinking of using a very minimal set of reStructuredText for the
docstrings, i.e., the set that looks just like asciidoc. The immediate
advantage is that ReST lists look like you would expect them to look:

  * foo
  * First paragraph in bar.

    Second paragraph in bar.

So we can use the docstrings directly when compiling a larger document
instead of having to add '+'-es all over the place as we do for asciidoc.

Bazaar uses this approach and converts their docstrings back to "really
plain text" by:

  def help_as_plain_text(text):
      """Minimal converter of reStructuredText to plain text."""
      lines = text.splitlines()
      result = []
      for line in lines:
          if line.startswith(':'):
              line = line[1:]
          elif line.endswith('::'):
              line = line[:-1]
          result.append(line)
      return "\n".join(result) + "\n"

which for our purposes could be replaced with a simple

  s.replace('::\n', ':\n')

call since I think the double-colon is all we would use at first (it
marks the following block as a literal block).

You can try out ReST here:

  http://rst2a.com/create/type/

-- 
Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.


More information about the Mercurial-devel mailing list