[PATCH 2 of 6] minimal reStructuredText parser

Martin Geisler mg at lazybytes.net
Sat Jul 11 14:13:59 UTC 2009


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

> On Fri, Jul 10, 2009 at 3:46 PM, Martin Geisler<mg at lazybytes.net> wrote:

>> 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.

They can use lists -- the point is that they remove the most obvious
reST syntax they use, which is '::'. A list in reST syntax looks just
like you would expect it to look and so they can just output it.

If people feel that my minirst parser is too fragile, then we could
simply do what Bazaar does and just turn '::' -> ':' and then otherwise
use the subset of reST syntax that looks "nice", i.e., the subset that
we are already using. That would still solve the problems with our man
and HTML pages.

>> 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.

The real test would be to have people run 'make doc' after changing a
docstring. That builds the HTML with rst2html and that command will
issue warnings and errors.

It's exactly the same situation as with asciidoc -- if you introduce
invalid asciidoc syntax in a docstring, then you'll also first find out
when doing 'make doc'.

I guess not many people did that and so we ended up with man and HTML
pages with lots of strange literal blocks. Try making your terminal
narrow and do 'man hg'. You'll notice that the text that originates from
docstrings is not reflown to fix your terminal width.

>> 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.

Ah, interesting. If you compare that with

  http://lazybytes.net/tmp/hg.1.html#commit

you'll see that gendoc.py adds the commas and so rst2html does a nice
job of interpreting the option list. However, when we display the help
with 'hg help', that part is displayed directly and bypasses the minirst
parser.

I suggest we unify the two code paths so that gendoc.py calls the same
code as 'hg help'.

The only place I know where the minirst parser parses an option list is
in 'hg help convert' where it formats the sort modes like this:

    [...] Sort modes have the following effects:

    --branchsort  convert from parent to child revision when possible, which
                  means branches are usually converted one after the other. It
                  generates more compact repositories.
    [...]

> 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!

That's good to hear :-)

> 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!"

Yeah, I noticed that too: the time for a 'make' in doc/ went down from
16 seconds to 6 seconds.

-- 
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://lists.mercurial-scm.org/pipermail/mercurial-devel/attachments/20090711/175e0726/attachment.asc>


More information about the Mercurial-devel mailing list