Misc. doc enhancements

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4041572

2 files changed, 18 insertions, 7 deletions

diff --git a/pkg_resources.txt b/pkg_resources.txt
index 8185c793..254051cc 100755
--- a/pkg_resources.txt
+++ b/pkg_resources.txt
@@ -136,7 +136,7 @@ directly alter ``sys.path`` at runtime, you may find these APIs useful:
     corresponding package in all distributions on ``sys.path`` that contain a
     package of that name.  (More precisely, if an importer's
     ``find_module(name)`` returns a loader, then it will also be searched for
-    the package's contents.)  Whenever a Distribution's ``to_install()`` method
+    the package's contents.)  Whenever a Distribution's ``activate()`` method
     is invoked, it checks for the presence of namespace packages and updates
     their ``__path__`` contents accordingly.
 
@@ -209,7 +209,7 @@ abbreviation for ``pkg_resources.working_set.require()``:
     For the syntax of requirement specifiers, see the section below on
     `Requirements Parsing`_.
 
-    Note: in general, it should not be necessary for you to call this method
+    In general, it should not be necessary for you to call this method
     directly.  It's intended more for use in quick-and-dirty scripting and
     interactive interpreter hacking than for production use. If you're creating
     an actual library or application, it's strongly recommended that you create
@@ -217,6 +217,16 @@ abbreviation for ``pkg_resources.working_set.require()``:
     there.  That way, tools like EasyInstall can automatically detect what
     requirements your package has, and deal with them accordingly.
 
+    Note that calling ``require('SomePackage')`` will not install
+    ``SomePackage`` if it isn't already present.  If you need to do this, you
+    should use the ``resolve()`` method instead, which allows you to pass an
+    ``installer`` callback that will be invoked when a needed distribution
+    can't be found on the local machine.  You can then have this callback
+    display a dialog, automatically download the needed distribution, or
+    whatever else is appropriate for your application. See the documentation
+    below on the ``resolve()`` method for more information, and also on the
+    ``obtain()`` method of ``Environment`` objects.
+
 ``run_script(requires, script_name)``
     Locate distribution specified by `requires` and run its `script_name`
     script.  `requires` must be a string containing a requirement specifier.
diff --git a/setuptools.txt b/setuptools.txt
index 69323d5b..a0d444e1 100755
--- a/setuptools.txt
+++ b/setuptools.txt
@@ -197,8 +197,8 @@ dots, such as ``2.4`` or ``0.5``.  Each series of digits is treated
 numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
 same release number, denoting the first subrelease of release 2.  But  ``2.10``
 is the *tenth* subrelease of release 2, and so is a different and newer release
-from ``2.1`` or ``2.1.0``.  Leading zeros are also ignored, so ``2.01`` is the
-same as ``2.1``.
+from ``2.1`` or ``2.1.0``.  Leading zeros within a series of digits are also
+ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
 
 Following a release number, you can have either a pre-release or post-release
 tag.  Pre-release tags make a version be considered *older* than the version
@@ -1349,11 +1349,12 @@ A final note for Subversion development: if you are using SVN revision tags
 as described in this section, it's a good idea to run ``setup.py develop``
 after each Subversion checkin or update, because your project's version number
 will be changing, and your script wrappers need to be updated accordingly.
+
 Also, if the project's requirements have changed, the ``develop`` command will
 take care of fetching the updated dependencies, building changed extensions,
-etc.  You should also inform your users of the need to run this command, if
-they are working from a Subversion checkout, rather than using EasyInstall to
-periodically fetch the latest version.
+etc.  Be sure to also remind any of your users who check out your project
+from Subversion that they need to run ``setup.py develop`` after every update
+in order to keep their checkout completely in sync.
 
 
 Distributing Extensions compiled with Pyrex