[Python-Dev] The docs, reloaded

[Stephen J. Turnbull]

Armin Ronacher writes:

 > rst is simpler than latex:
 > 
 > LaTeX:
 > 
 > \item[\code{*?}, \code{+?}, \code{??}] The \character{*},
 > \character{+}, and \character{?} qualifiers are all \dfn{greedy}; they
 > match as much text as possible.  Sometimes this behaviour isn't
 > desired; if the RE \regexp{<.*>} is matched against
 > \code{'<H1>title</H1>'}, it will match the entire string, and not just
 > \code{'<H1>'}.  Adding \character{?} after the qualifier makes it
 > perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as
 > \emph{few} characters as possible will be matched.  Using \regexp{.*?}
 > in the previous expression will match only \code{'<H1>'}.
 > 
 > Here the same in rst:
 > 
 > ``*?``, ``+?``, ``??``
 >    The ``'\*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`;
 >    they match as much text as possible.  Sometimes this behaviour isn't
 >    desired; if the RE :regexp:`<.\*>` is matched against
 >    ``'<H1>title</H1>'``, it will match the entire string, and not just
 >    ``'<H1>'``.  Adding ``'?'`` after the qualifier makes it perform the
 >    match in :dfn:`non-greedy` or :dfn:`minimal` fashion; as *few*
 >    characters as possible will be matched.  Using :regexp:`.\*?` in the
 >    previous expression will match only ``'<H1>'``.

IMO that pair of examples shows clearly that, in this application,
reST is not an improvement over LaTeX in terms of readability/
writability of source.  It's probably not worse, although I can't help
muttering "EIBTI".  In particular I find the "``'...'``" construct
horribly unreadable because it makes it hard to find the Python syntax
in all the reST.

I don't think that's an argument against switching to reST, though.
Georg's site speaks for itself.  Kudos!