[Python-Dev] The docs, reloaded
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
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.
More information about the Python-Dev