[Python-Dev] The docs, reloaded

[BJörn Lindqvist]

> > 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.
>
> Well. That was a bad example. But if you look at the converted sources and open
> the source file you can see that rst is a lot cleaner that latex for this type
> of documentation.

In your examples, I think the ReST version can be cleaned up quite a
bit. First by using the .. default-role:: literal directive so that
you can type `foo()` instead of using double back quotes and then you
can remove the redundant semantic markup. Like this:

`\*?`, `+?`, `??`
  The "`*`", "`+`" and "`?`" qualifiers are all *greedy*; they match
  as much text as possible. Sometimes this behaviour isn't desired; if
  the RE `<.*>` 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 *non-greedy* or *minimal*
  fashion; as *few* characters as possible will be matched. Using
  `.*?` in the previous expression will match only `'<H1>'`.

The above is the most readable version. For example, semantic markup
like :regexp:`<.\*>` doesn't serve any useful purpose. The end result
is that the text is typesetted with a fixed-width font, no matter if
you prepend :regexp: to it or not.


-- 
mvh Björn