[PATCH 0 of 6] reStructuredText help output

[Martin Geisler]

Hello everybody,

I've been talking about using reStructuredText for the help strings
and a couple of days ago I took at stab at turning the talk into code.

The idea is to format the docstrings in 'hg help' with a very simple
reStructuredText parser, and then use the full rst2html and rst2man
programs for building the HTML and man pages. There will thus be no
runtime dependency on Docutils -- it is only used for 'make doc'.

* The first changeset adds a .dir-locals.el file for Emacs, feel free
  to disregard this -- I can add it to a local ignore file instead.

* The second changeset adds the rst parser along with tests of it.
  Please take a look at the test input and output since it shows what
  it can do.

* The third changeset uses the new minirst module.

  To see how this effects the output, please take a look at the .out
  files from the unit tests. You can see that this mostly changes
  literal blocks which are no longer indented. This is a *feature* :-)
  We can now decide in one place that we want our literal blocks to be
  indented (I suggest we indent them with 2 spaces).

  Also, try resizing your terminal: the text is now re-wrapped
  automatically. This makes it easier for translators: they no longer
  have to wrap at 70 or 78 characters when this is redone on output.

* Having made the infrastructure, it was quite easy to adapt gendoc.py
  to produce rst formatted output -- this is changeset four.

  This has the big advantage of getting rid of the fixed width output.
  Try viewing the hg(1) man page in a narrow terminal window: all
  lines stick out to the right because they cannot wrap.

* Changesets five and six improves the formatting of the
  documentation.

Please compare

  http://www.selenic.com/mercurial/hg.1.html#remove
  http://lazybytes.net/tmp/hg.1.html#remove

and notice how the text is no longer fixed width (except for the table
which is sort of ASCII art) and how the argument descriptions at the
bottom include both monospace and serif fonts.

The sections are also formatted nicer in the hgrc(5) file:

  http://www.selenic.com/mercurial/hgrc.5.html#auth
  http://lazybytes.net/tmp/hgrc.5.html#auth

though that could of course also have been achieved with proper
asciidoc input.

The hgignore(5) file is here:

  http://www.selenic.com/mercurial/hgignore.5.html
  http://lazybytes.net/tmp/hgignore.5.html


Please let me know what you think of this! Maybe I've missed
something. There are probably still some commands where the output
look strange because of a corner case I haven't yet seen. So report
any problems and concerns back.

-- 
Martin