[Checkins] [ZODB-Dev] SVN: ZODB/trunk/src/persistent/wref.py Merged the rst formatting to the trunk

[Wichert Akkerman]

Christophe Combelles wrote:
> Zvezdan Petkovic a écrit :
>> On Oct 12, 2008, at 5:51 AM, Christophe Combelles wrote:
>>
>>> Log message for revision 92067:
>>>  Merged the rst formatting to the trunk
>> ...
>>
>>>     Here's an example. We'll start by creating a persistent object and
>>> -    a refernce to it:
>>> +    a reference to it::
>>>
>>> -    >>> import persistent.list
>>> -    >>> import ZODB.tests.util
>>> -    >>> ob = persistent.list.PersistentList()
>>> -    >>> ref = WeakRef(ob)
>>> -    >>> ref() is ob
>>> -    True
>>> +        >>> import persistent.list
>>> +        >>> import ZODB.tests.util
>>> +        >>> ob = persistent.list.PersistentList()
>>> +        >>> ref = WeakRef(ob)
>>> +        >>> ref() is ob
>>> +        True
>> Why have these changes been made?
>> This is now an invalid reST.
>>
>> The reST specification clearly states the difference between a literal  
>> block (started with ::) and a doctest block.
>>
>> Please see the examples in the section "Doctest blocks" of the  
>> specification at
>>
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
>>
>> At the bottom of that section is also stated.
>>
>> 	"Indentation is not required for doctest blocks."
>>
>> Yes, they can be indented, but there is absolutely no need to change a  
>> perfectly valid reST only to introduce a whitespace change in SVN and  
>> a wrong literal block use.
>>
>> Can we, please, refrain from such changes in the future unless we are  
>> absolutely certain that the changes are better than the original?
>>
>> This should be reverted.
> 
> 
> The only reason I did this is for readability in the APIDOC.

I would suggest that the better change is to fix apidoc.

Wichert.


-- 
Wichert Akkerman <wichert at wiggy.net>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.