[Python-Dev] The docs, reloaded (original) (raw)

BJörn Lindqvist 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.

-- mvh Björn

More information about the Python-Dev mailing list