[PATCH 2 of 6] minimal reStructuredText parser

[Martin Geisler]

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