[PATCH 2 of 6] minimal reStructuredText parser

Martin Geisler mg at lazybytes.net
Fri Jul 10 14:46:42 CDT 2009

Greg Ward <greg-hg at gerg.ca> writes:

> On Fri, Jul 10, 2009 at 7:54 AM, Martin Geisler<mg at lazybytes.net> wrote:

>> +"""simplified reStructuredText parser.
> Ugh.  I hate to rain on your parade, but is this *really* the right
> approach?  Where will we be in two years -- debating the finer points
> of "standard" reST versus "Mercurial" reST?  The whole point of reST
> is that there is a formal grammar and a well-tested reference
> implementation.  Granted, it's a big chunk of code that Mercurial
> really shouldn't depend for day-to-day use.
> So is this intended for generating "hg help" output, or for generating
> man pages, or for both?

This is *only* for 'hg help'. HTML and man pages are generated by the
real 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 :-)

The minirst parser should always parse a (strict) *subset* of all legal
reST documents. This means that there wont be any fight over what is
legal and what is not: if rst2html understand it, then it's legal. If
minirst understands it too, then you can use it in Mercurial docstrings.

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.

Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
Url : http://selenic.com/pipermail/mercurial-devel/attachments/20090710/5324641e/attachment.pgp 

More information about the Mercurial-devel mailing list