changes from pje feedback

pep-0376.txt

@@ -152,14 +152,14 @@ The RECORD format
 -----------------
 
 The `RECORD` file is composed of records, one line per installed file.
-Each record is composed of three elements separated by a `;` character:
+Each record is composed of three elements separated by a <tab> character:
 
 - the file's full **path**
 
- - if the installed file is located in a directory in `site-packages`,
-   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.
+ - 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.
 
  - if the installed file is located elsewhere in the system, a 
    '/'-separated absolute path is used.
@@ -181,11 +181,11 @@ Back to our `zlib` example, we will have::
 
 And the RECORD file will contain::
 
-    zlib/include/zconf.h;b690274f621402dda63bf11ba5373bf2;9544
-    zlib/include/zlib.h;9c4b84aff68aa55f2e9bf70481b94333;66188
-    zlib/lib/libz.a;e6d43fb94292411909404b07d0692d46;91128
-    zlib/share/man/man3/zlib.3;785dc03452f0508ff0678fba2457e0ba;4486
-    zlib-2.5.2.egg-info/PKG-INFO;6fe57de576d749536082d8e205b77748;195
+    zlib/include/zconf.h    b690274f621402dda63bf11ba5373bf2    9544
+    zlib/include/zlib.h 9c4b84aff68aa55f2e9bf70481b94333    66188
+    zlib/lib/libz.a e6d43fb94292411909404b07d0692d46    91128
+    zlib/share/man/man3/zlib.3  785dc03452f0508ff0678fba2457e0ba    4486
+    zlib-2.5.2.egg-info/PKG-INFO    6fe57de576d749536082d8e205b77748    195
     zlib-2.5.2.egg-info/RECORD
 
 Notice that:
@@ -202,6 +202,12 @@ library a set of APIs. The best place to put these APIs seems to be `pkgutil`.
 
 The new functions added in the package are :
 
+- get_projects() -> iterator
+
+  Provides an iterator that will return (name, path) tuples, where `name`
+  is the name of a registered project and `path` the path to its `egg-info`
+  directory.
+
 - get_egg_info(project_name) -> path or None
 
   Scans all elements in `sys.path` and looks for all directories ending with
@@ -219,26 +225,37 @@ The new functions added in the package are :
   Uses `get_egg_info` to get the `PKG-INFO` file, and returns a 
   `DistributionMetadata` instance that contains the metadata.
 
-- get_files(project_name) -> iterator of (path, hash, size, other_projects)
+- get_files(project_name, local=False) -> iterator of (path, hash, size, 
+                                                       other_projects)
 
   Uses `get_egg_info` to get the `RECORD` file, and returns an iterator.
 
   Each returned element is a tuple `(path, hash, size, other_projects)` where
   ``path``, ``hash``, ``size`` are the values found in the RECORD file.
 
+  `path` is the raw value founded in the RECORD file. If `local` is 
+  set to True, `path` will be translated to its real absolute path, using
+  the local path separator.
+
   `other_projects` is a tuple containing the name of the projects that are 
   also referring to this file in their own RECORD file (same path).
 
   If `other_projects` is empty, it means that the file is only referred by the
   current project. In other words, it can be removed if the project is removed.
 
-- get_egg_info_file(project_name, path) -> file object or None
+- get_egg_info_file(project_name, path, binary=False) -> file object or None
 
   Uses `get_egg_info` and gets any element inside the directory,
   pointed by its relative path. `get_egg_info_file` will perform
   an `os.path.join` on `get_egg_info(project_name)` and `path` to build the 
   whole path. 
 
+  `path` can be a '/'-separated path or can use the local separator. 
+  `get_egg_info_file` will automatically convert it using the platform path 
+  separator, to look for the file.
+
+  If `binary` is set True, the file will be opened using the binary mode.
+
 Let's use it with our `zlib` example::
 
     >>> from pkgutil import (get_egg_info, get_metadata, get_egg_info_file,