[PATCH 2 of 6] minimal reStructuredText parser

Greg Ward greg-hg at gerg.ca
Sat Jul 11 08:11:52 CDT 2009

On Fri, Jul 10, 2009 at 3:46 PM, Martin Geisler<mg at lazybytes.net> wrote:
> This is *only* for 'hg help'. HTML and man pages are generated by the
> real tools.

Oh, OK.  I missed your intro post when I responded to the patch.
(Blame Gmail for sorting threads by last-post time.)  (A real
craftsman *always* blames his tools. ;-)

> My first idea was to do what Bazaar does: output reST docstrings
> directly and only turn '::' into ':'. I then took that idea some steps
> further to reflow paragraphs and parse lists... and a bit more :-)

Gee, I had never noticed they did that.  Usually unprocessed reST
sticks out like a sore thumb.  Does that mean Bazaar help cannot use
lists at all?  I guess that'd be a win if we could.  And wrapping
paragraphs to the terminal width would be slick.

> This means that there wont be any fight over what is
> legal and what is not: if rst2html understand it, then it's legal.

Unless it violates the reST spec and rst2html just happens to accept
it.  Knowing how docutils is implemented, though, I imagine such cases
are rare.  ;-)

> If minirst understands it too, then you can use it in Mercurial docstrings.

That sounds simple and pragmatic.  Idea: what about a syntax checker
to make sure that people don't accidentally use non-minirst syntax in
docstrings?  If it runs with "make local" and can fail the build, that
could prevent some mistakes.

> Take option lists as an example. Real reST lets you write
>  --foo=FOO    the foo
>  -b, --bar B  the bar
> and the result will be "--foo" in monospace, "FOO" in italics and "the
> foo" in a serif font. We only support the much simpler
>  --foo=FOO  the foo
>  --bar      the bar
> which is still legal reST. Luckily, Mercurial only uses the simplest
> form of the option list and so the naive parser does the job.

Err... 'hg help commit' for me includes

 -u --user          record the specified user as committer

which is very similar to the optparse style above, except 1) no comma
(unimportant) and 2) no indication that --user takes an arg
("--user=USER").  ISTR grumblings about fixing #2, in which case we're
getting 1 char away from what real reST supports.

Anyways: this all sounds like a great change to me.  I'm being picky
because I want to see it done right, not because I'm against it!  I'm
not a fan of asciidoc, at least not since I wasted 20 min trying to
figure out why building git took so long and discovered just what
happens under the hood using asciidoc to turn text into roff.
*shudder*  "If you think docutils is slow, try asciidoc!"


More information about the Mercurial-devel mailing list