[pypy-svn] pypy documentation-cleanup: (arigo, cfbolz) document __builtins__ behaviour.

[cfbolz]

Author: Carl Friedrich Bolz <cfbolz at gmx.de>
Branch: documentation-cleanup
Changeset: r43806:8cf94069786d
Date: 2011-04-30 15:39 +0200
http://bitbucket.org/pypy/pypy/changeset/8cf94069786d/

Log:	(arigo, cfbolz) document __builtins__ behaviour.

diff --git a/pypy/doc/cpython_differences.rst b/pypy/doc/cpython_differences.rst
--- a/pypy/doc/cpython_differences.rst
+++ b/pypy/doc/cpython_differences.rst
@@ -127,7 +127,7 @@
 adopted by Jython or IronPython (or any other port of Python to Java or
 .NET, like PyPy itself).
 
-This affects the precise time at which __del__ methods are called, which
+This affects the precise time at which ``__del__`` methods are called, which
 is not reliable in PyPy (nor Jython nor IronPython).  It also means that
 weak references may stay alive for a bit longer than expected.  This
 makes "weak proxies" (as returned by ``weakref.proxy()``) somewhat less
@@ -137,12 +137,12 @@
 ``ReferenceError`` at any place that uses them.
 
 There are a few extra implications for the difference in the GC.  Most
-notably, if an object has a __del__, the __del__ is never called more
-than once in PyPy; but CPython will call the same __del__ several times
-if the object is resurrected and dies again.  The __del__ methods are
+notably, if an object has a ``__del__``, the ``__del__`` is never called more
+than once in PyPy; but CPython will call the same ``__del__`` several times
+if the object is resurrected and dies again.  The ``__del__`` methods are
 called in "the right" order if they are on objects pointing to each
 other, as in CPython, but unlike CPython, if there is a dead cycle of
-objects referencing each other, their __del__ methods are called anyway;
+objects referencing each other, their ``__del__`` methods are called anyway;
 CPython would instead put them into the list ``garbage`` of the ``gc``
 module.  More information is available on the blog `[1]`__ `[2]`__.
 
@@ -155,7 +155,7 @@
 and calling it a lot can lead to performance problem.
 
 Note that if you have a long chain of objects, each with a reference to
-the next one, and each with a __del__, PyPy's GC will perform badly.  On
+the next one, and each with a ``__del__``, PyPy's GC will perform badly.  On
 the bright side, in most other cases, benchmarks have shown that PyPy's
 GCs perform much better than CPython's.
 
@@ -234,5 +234,9 @@
   it could be supported, but then it will likely work in many
   *more* case on PyPy than on CPython 2.6/2.7.)
 
+* the ``__builtins__`` name is always referencing the ``__builtin__`` module,
+  never a dictionary as it sometimes is in CPython. Assigning to
+  ``__builtins__`` has no effect.
 
 .. include:: _ref.txt
+