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