[py-svn] r58517 - in py: dist/py/doc trunk/py/doc

[hpk at codespeak.net]

Author: hpk
Date: Wed Oct  1 11:24:24 2008
New Revision: 58517

Modified:
   py/dist/py/doc/misc.txt
   py/trunk/py/doc/misc.txt
Log:
clarify/better english for the cross-python version namespaces 


Modified: py/dist/py/doc/misc.txt
==============================================================================
--- py/dist/py/doc/misc.txt	(original)
+++ py/dist/py/doc/misc.txt	Wed Oct  1 11:24:24 2008
@@ -184,30 +184,29 @@
   * :source:`py/compat/`
   * :source:`py/builtin/`
 
-The py-lib contains some helpers that make writing scripts that work on various
-Python versions easier.
+The compat and builtin namespaces help to write code using newer python features on older python interpreters. 
 
 :api:`py.compat`
 ----------------
 
-:api:`py.compat` provides fixed versions (currently from Python 2.4.4) of
-various newer modules to be able to use them in various Python versions.
-Currently these are:
+:api:`py.compat` provides fixed versions (currently taken from Python 2.4.4) of
+a few selected modules to be able to use them across python versions.  Currently these are: 
 
  * doctest
  * optparse
  * subprocess
  * textwrap
 
-They are used by replacing the normal ``import ...`` by
-``from py.compat import ...``.
+Note that for example ``import doctest`` and ``from py.compat import doctest`` result
+into two different module objects no matter what Python version you are using.  
+So you should only use exactly one of these to avoid confusion in your program.  
 
 :api:`py.builtin`
 -----------------
 
-:api:`py.builtin` provides various builtins that were added in later Python
-versions. If the used Python version used does not provide these builtins, they
-are pure-Python reimplementations. These currently are:
+:api:`py.builtin` provides builtin functions/types that were added in later Python
+versions. If the used Python version used does not provide these builtins the
+py lib provides some reimplementations. These currently are:
 
  * enumerate
  * reversed
@@ -217,4 +216,3 @@
    module)
 
 :api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
-

Modified: py/trunk/py/doc/misc.txt
==============================================================================
--- py/trunk/py/doc/misc.txt	(original)
+++ py/trunk/py/doc/misc.txt	Wed Oct  1 11:24:24 2008
@@ -184,30 +184,29 @@
   * :source:`py/compat/`
   * :source:`py/builtin/`
 
-The py-lib contains some helpers that make writing scripts that work on various
-Python versions easier.
+The compat and builtin namespaces help to write code using newer python features on older python interpreters. 
 
 :api:`py.compat`
 ----------------
 
-:api:`py.compat` provides fixed versions (currently from Python 2.4.4) of
-various newer modules to be able to use them in various Python versions.
-Currently these are:
+:api:`py.compat` provides fixed versions (currently taken from Python 2.4.4) of
+a few selected modules to be able to use them across python versions.  Currently these are: 
 
  * doctest
  * optparse
  * subprocess
  * textwrap
 
-They are used by replacing the normal ``import ...`` by
-``from py.compat import ...``.
+Note that for example ``import doctest`` and ``from py.compat import doctest`` result
+into two different module objects no matter what Python version you are using.  
+So you should only use exactly one of these to avoid confusion in your program.  
 
 :api:`py.builtin`
 -----------------
 
-:api:`py.builtin` provides various builtins that were added in later Python
-versions. If the used Python version used does not provide these builtins, they
-are pure-Python reimplementations. These currently are:
+:api:`py.builtin` provides builtin functions/types that were added in later Python
+versions. If the used Python version used does not provide these builtins the
+py lib provides some reimplementations. These currently are:
 
  * enumerate
  * reversed
@@ -217,4 +216,3 @@
    module)
 
 :api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
-