[PATCH 2 of 6] minimal reStructuredText parser
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