included roadmap and a few typo fixes. fixes #47

--HG--
branch : distribute
extra : rebase_source : a6677457030f92ff8da952fe47b4449f17b6f431

docs/index.txt

@@ -6,11 +6,11 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   roadmap
+   python3
    setuptools
    easy_install
    pkg_resources
-   python3
-
 
 Indices and tables
 ==================

docs/roadmap.txt

+=======
+Roadmap
+=======
+
+Distribute has two branches:
+
+- 0.6.x : provides a Setuptools-0.6c9 compatible version
+- 0.7.x : will provide a refactoring
+
+0.6.x
+=====
+
+Not "much" is going to happen here, we want this branch to be helpful
+to the community *today* by addressing the 40-or-so bugs
+that were found in Setuptools and never fixed. This is eventually
+happen soon because its development is
+fast : there are up to 5 commiters that are working on it very often
+(and the number grows weekly.)
+
+The biggest issue with this branch is that it is providing the same
+packages and modules setuptools does, and this
+requires some bootstrapping work where we make sure once Distribute is
+installed, all Distribution that requires Setuptools
+will continue to work. This is done by faking the metadata of
+Setuptools 0.6c9. That's the only way we found to do this.
+
+There's one major thing though: thanks to the work of Lennart, Alex,
+Martin, this branch supports Python 3,
+which is great to have to speed up Py3 adoption.
+
+The goal of the 0.6.x is to remove as much bugs as we can, and try if
+possible to remove the patches done
+on Distutils. We will support 0.6.x maintenance for years and we will
+promote its usage everywhere instead of
+Setuptools.
+
+Some new commands are added there, when they are helpful and don't
+interact with the rest. I am thinking
+about "upload_docs" that let you upload documentation to PyPI. The
+goal is to move it to Distutils
+at some point, if the documentation feature of PyPI stays and starts to be used.
+
+0.7.x
+=====
+
+We've started to refactor Distribute with this roadmap in mind (and
+no, as someone said, it's not vaporware,
+we've done a lot already)
+
+- 0.7.x can be installed and used with 0.6.x
+
+- easy_install is going to be deprecated ! use Pip !
+
+- the version system will be deprecated, in favor of the one in Distutils
+
+- no more Distutils monkey-patch that happens once you use the code
+ (things like 'from distutils import cmd; cmd.Command = CustomCommand')
+
+- no more custom site.py (that is: if something misses in Python's
+  site.py we'll add it there instead of patching it)
+
+- no more namespaced packages system, if PEP 381 (namespaces package
+  support) makes it to 2.7
+
+- The code is splitted in many packages and might be distributed under
+  several distributions.
+
+ - distribute.resources: that's the old pkg_resources, but
+   reorganized in clean, pep-8 modules. This package will
+   only contain the query APIs and will focus on being PEP 376
+   compatible. We will promote its usage and see if Pip wants
+   to use it as a basis. 
+   It will probably shrink a lot though, once the stdlib provides PEP 376 support.
+
+ - distribute.entrypoints: that's the old pkg_resources entry points
+   system, but on its own. it uses distribute.resources
+
+ - distribute.index: that's package_index and a few other things.
+   everything required to interact with PyPI. We will promote
+   its usage and see if Pip wants to use it as a basis.
+
+ - distribute.core (might be renamed to main): that's everything
+   else, and uses the other packages.
+
+Goal: A first release before (or when) Python 2.7 / 3.2 is out.
+

docs/setuptools.txt

-======================================================
-Building and Distributing Packages with ``setuptools``
-======================================================
+==================================================
+Building and Distributing Packages with Distribute
+==================================================
 
-``setuptools`` is a collection of enhancements to the Python ``distutils``
+``Distribute`` is a collection of enhancements to the Python ``distutils``
 (for Python 2.3.5 and up on most platforms; 64-bit platforms require a minimum
 of Python 2.4) that allow you to more easily build and distribute Python
 packages, especially ones that have dependencies on other packages.
@@ -2433,9 +2433,9 @@ The ``upload_docs`` command has the following options:
     http://pypi.python.org/pypi (i.e., the main PyPI installation).
 
 
-------------------------------------
-Extending and Reusing ``setuptools``
-------------------------------------
+--------------------------------
+Extending and Reusing Distribute
+--------------------------------
 
 Creating ``distutils`` Extensions
 =================================