[Python-Dev] The docs, reloaded
bjourne at gmail.com
Tue May 22 19:52:16 CEST 2007
> > 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.
More information about the Python-Dev