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

Georg Brandl g.brandl at gmx.net
Tue May 22 21:36:37 CEST 2007

BJörn Lindqvist schrieb:

> 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:

I've already assigned the default role to var since it's used most frequently.

Having two ways of spelling literal code is wasting markup, for me.

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.

Yes, there are a few semantic roles that may be obsolete.

Georg

More information about the Python-Dev mailing list