clarified the egg.info part and added references about fedora and debian

pep-0376.txt

@@ -85,23 +85,35 @@ 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.
 
-The problem is that many people use `easy_install` (from the `setuptools`
+Another project called `setuptools` [#setuptools]_ has introduced two new 
-project [#setuptools]_) or `pip` [#pip]_ to install their packages, and 
+formats to install distributions:
-these third-party tools do not install packages in the same way that Distutils 
-does:
 
-- `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory
+- a self-contained `.egg` directory, that contains all the distribution files
-  and adds a `PKG-INFO` file inside this directory. The `.egg` directory
+  and the distribution metadata in a file called `PKG-INFO` in a subdirectory
-  contains all the elements of the distribution that are supposed to be
+  called `EGG-INFO`. Other files are created in that directory for 
-  installed in `site-packages` and is placed in the `site-packages`
+  `setuptools` needs.
-  directory.
 
-- `pip` creates an `.egg-info` directory inside the `site-packages` directory
+- a `.egg-info` directory installed in `site-packages`, that contains the same
-  and adds a `PKG-INFO` file inside it. Elements of the distribution are then
+  files `EGG-INFO` has in the `.egg` format.
-  installed in various places like Distutils does.
 
-They both add other files in the `EGG-INFO` or `.egg-info` directory and
+The first format is automatically used when you install a distribution that
-create or modify `.pth` files.
+uses ``setuptools.setup`` function in its setup.py file, instead of
+``distutils.core.setup``. 
+
+The `setuptools` project also provides an executable script called 
+`easy_install` that will install all istributions, including distutils-based
+ones in self-contained `.egg` directories.
+
+If you want to have a standalone `.egg.info` directory with setuptools-based 
+distributions, e.g. the second `setuptools` format, you have to force it 
+using the `-–single-version-externally-managed` option **or** the `--root` 
+option.
+
+This option is used by :
+
+- the `pip` [#pip]_ installer 
+- the Fedora packagers [#fedora]_.
+- the Debian packagers [#debian]_.
 
 Uninstall information
 ---------------------
@@ -139,8 +151,8 @@ To address those issues, this PEP proposes a few changes:
 .egg-info becomes a directory
 =============================
 
-The `EggFormats` standard from setuptools proposes two formats to install the
+As explained earlier, the `EggFormats` standard from `setuptools` proposes two 
-metadata information of a distribution:
+formats to install the metadata information of a distribution:
 
 - A self-contained directory that can be zipped or left unzipped and contains
   the distribution files *and* an `.egg-info` directory containing the 
@@ -300,7 +312,7 @@ 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 seems to be `pkgutil`.
+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
 (so it works with files included in Zip files, see PEP 273 for more details
@@ -387,7 +399,7 @@ class so its methods work with an `.egg.info` directory located in a zip 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
@@ -409,7 +421,7 @@ It also provides one extra method besides the ones from ``set``:
 
 
 ZippedDistributionDir class
----------------------------------
+---------------------------
 
 A ``ZippedDistributionDir`` is provided. It overrides the
 ``DistributionDir`` class so its methods work with a Zip file.
@@ -422,7 +434,7 @@ 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.
@@ -687,6 +699,11 @@ References
 .. [#pep278]
    http://www.python.org/dev/peps/pep-0278
 
+.. [#fedora]
+   http://fedoraproject.org/wiki/Packaging/Python/Eggs#Providing_Eggs_using_Setuptools
+
+.. [#debian]
+   http://wiki.debian.org/DebianPython/NewPolicy
 
 Aknowledgments
 ==============