removed implementation details from the PEP. A reference is kept

pep-0376.txt

@@ -85,29 +85,30 @@ extra module and executable scripts, three elements will be installed in
 Some executable scripts, such as `rst2html.py`, will also be added in the
 `bin` directory of the Python installation.
 
-Another project called `setuptools` [#setuptools]_ has introduced two new 
+Another project called `setuptools` [#setuptools]_ has two other formats 
-formats to install distributions:
+to install distributions, called `EggFormats` [#eggformats]_:
 
 - a self-contained `.egg` directory, that contains all the distribution files
   and the distribution metadata in a file called `PKG-INFO` in a subdirectory
-  called `EGG-INFO`. Other files are created in that directory for 
+  called `EGG-INFO`. `setuptools` creates other fils in that directory that can
-  `setuptools` needs.
+  be considered as complementary metadata.
 
 - a `.egg-info` directory installed in `site-packages`, that contains the same
   files `EGG-INFO` has in the `.egg` format.
 
 The first format is automatically used when you install a distribution that
-uses ``setuptools.setup`` function in its setup.py file, instead of
+uses the ``setuptools.setup`` function in its setup.py file, instead of
-``distutils.core.setup``. 
+the ``distutils.core.setup`` one.
 
 The `setuptools` project also provides an executable script called 
-`easy_install` that will install all istributions, including distutils-based
+`easy_install` [#easyinstall]_ that will install all distributions, including 
-ones in self-contained `.egg` directories.
+distutils-based ones in self-contained `.egg` directories.
 
-If you want to have a standalone `.egg.info` directory with setuptools-based 
+If you want to have a standalone `.egg.info` directory distributions, e.g. 
-distributions, e.g. the second `setuptools` format, you have to force it 
+the second `setuptools` format, you have to force it when you work
-using the `-–single-version-externally-managed` option **or** the `--root` 
+with a setuptools-based distribution or with the `easy_install` script.
-option.
+You can force it by using the `-–single-version-externally-managed` option 
+**or** the `--root` option.
 
 This option is used by :
 
@@ -140,8 +141,8 @@ What this PEP proposes
 
 To address those issues, this PEP proposes a few changes:
 
-- A new `.egg-info` structure using a directory, based on one form of
+- A new `.egg-info` structure using a directory, based on one format of
-  the `EggFormats` standard from `setuptools` [#eggformats]_.
+  the `EggFormats` standard from `setuptools`.
 - New APIs in `pkgutil` to be able to query the information of installed
   distributions.
 - A de-facto replacement for PEP 262
@@ -314,18 +315,31 @@ New APIs in pkgutil
 To use the `.egg-info` directory content, we need to add in the standard
 library a set of APIs. The best place to put these APIs is `pkgutil`.
 
-The API is organized in five classes that work with directories and Zip files
+Query functions
-(so it works with files included in Zip files, see PEP 273 for more details
+---------------
-[#pep273]_.
 
-- ``Distribution``: manages an `.egg-info` directory.
+The new functions added in the ``pkgutil`` are :
-- ``ZippedDistribution``: manages an `.egg-info` directory contained in a zip
+
-  file.
+- ``get_distributions()`` -> iterator of ``Distribution`` instances.
-- ``DistributionDir``: manages a directory that contains some `.egg-info`
+
-  directories.
+  Provides an iterator that looks for ``.egg-info`` directories in 
-- ``ZippedDistributionDir``: manages a zipped directory that contains
+  ``sys.path`` and returns ``Distribution`` instances for
-  some `.egg.info` directory.
+  each one of them.
-- ``DistributionDirMap``: manages ``DistributionDir`` instances.
+
+- ``get_distribution(name)`` -> ``Distribution`` or None.
+
+  Scans all elements in ``sys.path`` and looks for all directories ending with
+  ``.egg-info``. Returns a ``Distribution`` corresponding to the 
+  ``.egg-info`` directory that contains a PKG-INFO that matches `name` 
+  for the `name` metadata.
+
+  Notice that there should be at most one result. The first result founded
+  will be returned. If the directory is not found, returns None.
+
+- ``get_file_users(path)`` -> iterator of ``Distribution`` instances.
+
+  Iterates over all distributions to find out which distributions uses ``path``.
+  ``path`` can be a local absolute path or a relative '/'-separated path.
 
 Distribution class
 ------------------
@@ -385,145 +399,14 @@ And following methods:
   If ``local`` is ``True``, each path is transformed into a
   local absolute path. Otherwise the raw value from `RECORD` is returned.
 
-ZippedDistribution class
-------------------------
 
-A ``ZippedDistribution`` class is provided. It overrides the ``Distribution``
+Notice that the API is organized in five classes that work with directories 
-class so its methods work with an `.egg.info` directory located in a zip file.
+and Zip files (so it works with files included in Zip files, see PEP 273 for
+more details [#pep273]_). These classes are described in the documentation 
+of the prototype implementation for interested readers [#prototype]_.
 
-``ZippedDistribution(zipfile, path)`` -> instance
+Usage example
-
+-------------
-  Creates a ``ZippedDistribution`` instance for the given relative ``path``
-  located in the ``zipfile`` file.
-
-Other public methods and attributes are similar to  ``Distribution``.
-
-DistributionDir class
----------------------
-
-A new class called ``DistributionDir`` is created with a path
-corresponding to a directory. For each `.egg-info` directory founded in
-`path`, the class creates a corresponding ``Distribution``.
-
-The class is a ``set`` of ``Distribution`` instances. ``DistributionDir``
-provides a ``path`` attribute corresponding to the path is was created with.
-
-``DistributionDir(path)`` -> instance
-
-  Creates a ``DistributionDir`` instance for the given ``path``.
-
-It also provides one extra method besides the ones from ``set``:
-
-- ``get_file_users(path)`` -> Iterator of ``Distribution``.
-
-  Returns all ``Distribution`` which uses ``path``, by calling
-  ``Distribution.uses(path)`` on all ``Distribution`` instances.
-
-
-ZippedDistributionDir class
----------------------------
-
-A ``ZippedDistributionDir`` is provided. It overrides the
-``DistributionDir`` class so its methods work with a Zip file.
-
-``ZippedDistributionDir(path)`` -> instance
-
-  Creates a ``ZippedDistributionDir`` instance for the given ``path``.
-
-Other public methods and attributes are similar to  ``DistributionDir``.
-
-
-DistributionDirMap class
-------------------------
-
-A new class called ``DistributionDirMap`` is created. It's a collection of
-``DistributionDir`` and ``ZippedDistributionDir`` instances.
-
-``DistributionDirMap(paths=None, use_cache=True)`` -> instance
-
-  If ``paths`` is not not, it's a sequence of paths the constructor loads
-  in the instance.
-
-  The constructor also takes an optional ``use_cache`` argument.
-  When it's ``True``, ``DistributionDirMap`` will use a global
-  cache to reduce the numbers of I/O accesses and speed up the lookups.
-
-  The cache is a global mapping containing ``DistributionDir`` and
-  ``ZippedDistributionDir`` instances. When a
-  ``DistributionDirMap`` object is created, it will use the cache to
-  add an entry for each path it visits, or reuse existing entries. The
-  cache usage can be disabled at any time with the ``use_cache`` attribute.
-
-  The cache can also be emptied with the global ``purge_cache`` function.
-
-The class is a ``dict`` where the values are ``DistributionDir``
-and ``ZippedDistributionDir`` instances and the keys are their path
-attributes.
-
-``DistributionDirMap`` also provides the following methods besides the ones
-from ``dict``:
-
-- ``load(*paths)``
-
-  Creates and adds ``DistributionDir`` (or
-  ``ZippedDistributionDir``) instances corresponding to ``paths``.
-
-- ``reload()``
-
-  Reloads existing entries.
-
-- ``get_distributions()`` -> Iterator of ``Distribution`` (or
-  ``ZippedDistribution``) instances.
-
-  Iterates over all ``Distribution`` and ``ZippedDistribution`` contained
-  in ``DistributionDir`` and ``ZippedDistributionDir`` instances.
-
-- ``get_distribution(dist_name)`` -> ``Distribution`` (or
-  ``ZippedDistribution``) or None.
-
-  Returns a ``Distribution`` (or ``ZippedDistribution``) instance for the
-  given distribution name. If not found, returns None.
-
-- ``get_file_users(path)`` -> Iterator of ``Distribution`` (or
-  ``ZippedDistribution``) instances.
-
-  Iterates over all distributions to find out which distributions use the file.
-  Returns ``Distribution`` (or ``ZippedDistribution``) instances.
-
-.egg-info functions
--------------------
-
-The new functions added in the ``pkgutil`` are :
-
-- ``get_distributions()`` -> iterator of ``Distribution`` (or
-  ``ZippedDistribution``) instance.
-
-  Provides an iterator that looks for ``.egg-info`` directories in ``sys.path``
-  and returns ``Distribution`` (or ``ZippedDistribution``) instances for
-  each one of them.
-
-- ``get_distribution(name)`` -> ``Distribution``  (or ``ZippedDistribution``)
-  or None.
-
-  Scans all elements in ``sys.path`` and looks for all directories ending with
-  ``.egg-info``. Returns a ``Distribution``  (or ``ZippedDistribution``)
-  corresponding to the ``.egg-info`` directory that contains a PKG-INFO that
-  matches `name` for the `name` metadata.
-
-  Notice that there should be at most one result. The first result founded
-  will be returned. If the directory is not found, returns None.
-
-- ``get_file_users(path)`` -> iterator of ``Distribution``  (or
-  ``ZippedDistribution``) instances.
-
-  Iterates over all distributions to find out which distributions uses ``path``.
-  ``path`` can be a local absolute path or a relative '/'-separated path.
-
-All these functions use the same global instance of ``DistributionDirMap``
-to use the cache. Notice that the cache is never emptied explicitely.
-
-Example
--------
 
 Let's use some of the new APIs with our `docutils` example::
 
@@ -687,6 +570,9 @@ References
 .. [#setuptools]
    http://peak.telecommunity.com/DevCenter/setuptools
 
+.. [#easyinstall]
+   http://peak.telecommunity.com/DevCenter/EasyInstall
+
 .. [#pip]
    http://pypi.python.org/pypi/pip
 
@@ -705,6 +591,9 @@ References
 .. [#debian]
    http://wiki.debian.org/DebianPython/NewPolicy
 
+.. [#prototype]
+   http://bitbucket.org/tarek/pep376/   
+
 Aknowledgments
 ==============