[Python-Dev] The docs, reloaded

[Georg Brandl]

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