added obsoletes API and changed the file path strategy in RECORD

pep-0376.txt

@@ -194,10 +194,26 @@ these options:
 - quoting char :  `"`.
 - line terminator : ``os.linesep`` (so ``\r\n`` or ``\n``)
 
+When a distribution is installed, files can be installed under:
+
+- the **base location**: path defined by the ``--install-lib`` option,
+  which defaults to the site-packages directory.
+
+- the **installation prefix**: path defined by the ``--prefix`` option, which
+  defaults to ``sys.prefix``.
+
+- any other path on the system.
+
+
 Each record is composed of three elements:
 
-- the file's **path**, relative to ``sys.prefix``. When the
-  file is not under ``sys.prefix``, an absolute path is used.
+- the file's **path**
+  - a '/'-separated path, relative to the **base location**, if the file is
+    under the **base location**.
+  - a '/'-separated path, relative to the **base location**, if the file
+    is under the  **installation prefix** AND if the **base location** is a
+    subpath of the **installation prefix**.
+  - an absolute path, using the local platform separator
 
 - the **MD5** hash of the file, encoded in hex. Notice that `pyc` and `pyo`
   generated files don't have any hash because they are automatically produced
@@ -320,6 +336,17 @@ The new functions added in the ``pkgutil`` module are :
 
 - ``get_distribution(name)`` -> ``Distribution`` or None.
 
+- ``obsoletes_distribution(name, version=None)`` -> iterator of ``Distribution``
+  instances.
+
+  Iterates over all distributions to find which distributions *obsolete*
+  ``name``. If a ``version`` is provided, it will be used to filter the results.
+
+- ``provides_distribution(name, version=None)`` -> iterator of ``Distribution``
+  instances.
+
+  Iterates over all distributions to find which distributions *provide*
+  ``name``. If a ``version`` is provided, it will be used to filter the results.
   Scans all elements in ``sys.path`` and looks for all directories ending with
   ``.dist-info``. Returns a ``Distribution`` corresponding to the
   ``.dist-info`` directory that contains a METADATA that matches `name`
@@ -342,7 +369,7 @@ Distribution class
 
 A new class called ``Distribution`` is created with the path of the
 `.dist-info` directory provided to the constructor. It reads the metadata
-contained in `METADATA` when it is instanciated.
+contained in `METADATA` when it is instantiated.
 
 ``Distribution(path)`` -> instance