[svn r58517] clarify/better english for the cross-python version namespaces

--HG--
branch : trunk

py/doc/misc.txt

@@ -184,30 +184,29 @@ sources:
   * :source:`py/compat/`
   * :source:`py/builtin/`
 
-The py-lib contains some helpers that make writing scripts that work on various
+The compat and builtin namespaces help to write code using newer python features on older python interpreters. 
-Python versions easier.
 
 :api:`py.compat`
 ----------------
 
-:api:`py.compat` provides fixed versions (currently from Python 2.4.4) of
+:api:`py.compat` provides fixed versions (currently taken from Python 2.4.4) of
-various newer modules to be able to use them in various Python versions.
+a few selected modules to be able to use them across python versions.  Currently these are: 
-Currently these are:
 
  * doctest
  * optparse
  * subprocess
  * textwrap
 
-They are used by replacing the normal ``import ...`` by
+Note that for example ``import doctest`` and ``from py.compat import doctest`` result
-``from py.compat import ...``.
+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
+: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, they
+versions. If the used Python version used does not provide these builtins the
-are pure-Python reimplementations. These currently are:
+py lib provides some reimplementations. These currently are:
 
  * enumerate
  * reversed
@@ -217,4 +216,3 @@ are pure-Python reimplementations. These currently are:
    module)
 
 :api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
-