[Python-Dev] The docs, reloaded

[Armin Ronacher]

Hoi,

Fred L. Drake, Jr. <fdrake <at> acm.org> writes:

> 
> On Monday 21 May 2007, A.M. Kuchling wrote:
>  > Disadvantages:
>  >
>  > * reST markup isn't much simpler than LaTeX.
> 
> * reST doesn't support nested markup, which is used in the current
>   documentation.

For a lightweight markup language that is human readable (which rst certainly
is) the syntax is surprisingly powerful. You can nest any block tag and I'm not
sure how often you have to nest roles and stuff like that. The goal of the new
docs is a less complex syntax and currently nothing beats reStructuredText in
terms of readability and possibilities.

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

Regards,
Armin