Fixes from python-dev feedbacks

pep-0376.txt

@@ -72,17 +72,18 @@ various subcommands.
 The `install_egg_info` subcommand is called during this process, in order to
 create an `.egg-info` file in the `purelib` directory.
 
-For example, if the `zlib` distribution (which contains one package) is 
-installed, two elements will be installed in `site-packages`::
+For example, for the `docutils` distribution, which contains one package an
+extra module and executable scripts, three elements will be installed in
+`site-packages`::
 
- - zlib
- - zlib-2.5.2-py2.4.egg-info
+ - docutils : the docutils pakage
+ - roman.py : an extra module used by docutils
+ - docutils-0.5-py2.6.egg-info : a file containing the distribution metadata
+   as described in PEP 314 [#pep314]_. This file corresponds to the file
+   called `PKG-INFO`, built by the `sdist` command.
 
-Where `zlib` is a Python package, and `zlib-2.5.2-py2.4.egg-info` is
-a file containing the distribution metadata as described in PEP 314 [#pep314]_.
-
-This file corresponds to the file called `PKG-INFO`, built by
-the `sdist` command.
+Some executable scripts such as `rst2html.py` will also be added in the `bin`
+directory of the Python installation.
 
 The problem is that many people use `easy_install` (setuptools [#setuptools]_)
 or `pip` [#pip]_ to install their packages, and these third-party tools do not
@@ -157,11 +158,12 @@ Although it will impact the `setuptools` and `pip` projects, but given
 the fact that they already work with a directory that contains a `PKG-INFO`
 file, the change will have no deep consequences.
 
-For example, if the `zlib` package is installed, the elements that
+For example, if the `docutils` package is installed, the elements that
 will be installed in `site-packages` will become::
 
-    - zlib
-    - zlib-2.5.2.egg-info/
+    - docutils
+    - roman.py
+    - docutils-0.5-py2.6.egg-info/
         PKG-INFO
 
 The syntax of the egg-info directory name is as follows::
@@ -179,8 +181,8 @@ filename-escaped form. Any '-' characters are currently replaced with '_'.
 
 Examples::
 
-    >>> egginfo_dirname('zlib', '2.5.2')
-    'zlib-2.5.2.egg-info'
+    >>> egginfo_dirname('docutils', '0.5')
+    'docutils-0.5.egg-info'
 
     >>> egginfo_dirname('python-ldap', '2.5')
     'python_ldap-2.5.egg-info'
@@ -213,13 +215,13 @@ the `excel` dialect, which uses these options to read the file:
 
 - field delimiter : `,`
 - quoting char :  `"`.
-- line terminator : `\r\n`
+- line terminator : ``os.linesep`` (so `\r\n` or `\r`)
 
 Each record is composed of three elements.
 
 - the file's full **path**
 
- - if the installed file is located in the directory where the .egg-info
+ - if the installed file is located in the directory where the `.egg-info`
    directory of the package is located, it will be a '/'-separated relative
    path, no matter what is the target system. This makes this information
    cross-compatible and allows simple installation to be relocatable.
@@ -228,7 +230,10 @@ Each record is composed of three elements.
    '/'-separated absolute path is used.
 
 - the **MD5** hash of the file, encoded in hex. Notice that `pyc` and `pyo`
-  generated files will not have a hash.
+  generated files will not have a hash because they are automatically produced
+  from `py` files. So checking the hash of the corresponding `py` file is
+  enough to decide if the file and its associated `pyc` or `pyo` files have
+  changed.
 
 - the file's size in bytes
 
@@ -236,6 +241,11 @@ The ``csv`` module with its default options will be used to generate this file,
 so the field separator will be ",". Any "," characters found within a field
 will be escaped automatically by ``csv``.
 
+When the file is read, the `U` option will be used so the universal newline
+support (see PEP 278 [pep278]_) will be activated, avoiding any trouble
+reading a file produced on a platform that uses a different new line
+terminator.
+
 Example
 -------
 
@@ -364,7 +374,7 @@ provides a ``path`` attribute corresponding to the path is was created with.
 
 It also provides two methods besides the ones from ``set``:
 
-- ``file_users(path)`` -> Iterator of ``Distribution``.
+- ``get_file_users(path)`` -> Iterator of ``Distribution``.
 
   Returns all ``Distribution`` which uses ``path``, by calling
   ``Distribution.uses(path)`` on all ``Distribution`` instances.
@@ -405,12 +415,7 @@ attributes.
 ``DistributionDirectories`` also provides the following methods besides the ones
 from ``dict``::
 
-- ``append(path)``
-
-  Creates an ``DistributionDirectory`` (or ``ZippedDistributionDirectory``)
-  instance for ``path`` and adds it in the mapping.
-
-- ``load(paths)``
+- ``load(*paths)``
 
   Creates and adds ``DistributionDirectory`` (or
   ``ZippedDistributionDirectory``) instances corresponding to ``paths``.
@@ -482,7 +487,7 @@ Let's use some of the new APIs with our `zlib` example::
     '2.5.2'
 
     >>> for path, hash, size in dist.get_installed_files()::
-    ...     print '%s %s %d %s' % (path, hash, size)
+    ...     print '%s %s %d' % (path, hash, size)
     ...
     zlib/include/zconf.h b690274f621402dda63bf11ba5373bf2 9544
     zlib/include/zlib.h 9c4b84aff68aa55f2e9bf70481b94333 66188
@@ -622,6 +627,10 @@ References
 .. [#pep273]
    http://www.python.org/dev/peps/pep-0273
 
+.. [#pep2738]
+   http://www.python.org/dev/peps/pep-0278
+
+
 .. [distutils]
    http://docs.python.org/distutils