[PATCH 0 of 6] reStructuredText help output

Martin Geisler mg at lazybytes.net
Fri Jul 10 13:04:12 CDT 2009


Martin Geisler <mg at lazybytes.net> writes:

> Hello everybody,
>
> I've been talking about using reStructuredText for the help strings
> and a couple of days ago I took at stab at turning the talk into code.

In my eager to describe all the wonderful new features, I forgot to
mention some of the potential problems:

* third-party extensions. The docstring of a third-party extension can
  turn up "funny" if it happens to be written in a way that isn't parsed
  correctly by the rst parser.

  It is mostly a problem for literal blocks (program output and config
  settings) which will be turned into a single paragraph when they
  aren't prefixed by the '::'.

  I've tried to make the parser safe, though. By that I mean it should
  not throw exceptions, no matter what input you throw at it. At worst,
  things will be rendered funny.

  We could add a flag that extensions can set in order to activate the
  parser... but that would mean that old extensions are not "upgraded"
  automatically and so miss out on the fun.

* I have cheated in some places by declaring stuff a literal block when
  it is really not. This is done for the list of enabled/disabled
  extensions, for example.

  Marking it as a literal block means that it will be rendered "as-is"
  in the terminal and one cannot tell the difference, but it will be
  ASCII-arg in the HTML pages.

Probably more stuff -- let me know when you find it :-)

-- 
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/bd54546f/attachment.pgp 


More information about the Mercurial-devel mailing list