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

[Christophe Combelles]

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.

As an example, currently the first doctest block looks like this:

 >>> import persistent.list >>> import ZODB.tests.util >>> ob = 
persistent.list.PersistentList() >>> ref = WeakRef(ob) >>> ref() is ob True

Just by indenting, the appearance is OK. Since indenting is permitted in the 
specifications, I think this change is better

regards,
Christophe



> 
> 	Zvezdan
> 
> 
> _______________________________________________
> For more information about ZODB, see the ZODB Wiki:
> http://www.zope.org/Wikis/ZODB/
> 
> ZODB-Dev mailing list  -  ZODB-Dev at zope.org
> http://mail.zope.org/mailman/listinfo/zodb-dev
> 
>