[Python-checkins] commit of r41572 - sandbox/trunk/setuptools

[phillip.eby]

Author: phillip.eby
Date: Thu Dec  1 02:18:03 2005
New Revision: 41572

Modified:
   sandbox/trunk/setuptools/pkg_resources.txt
   sandbox/trunk/setuptools/setuptools.txt
Log:
Misc. doc enhancements


Modified: sandbox/trunk/setuptools/pkg_resources.txt
==============================================================================
--- sandbox/trunk/setuptools/pkg_resources.txt	(original)
+++ sandbox/trunk/setuptools/pkg_resources.txt	Thu Dec  1 02:18:03 2005
@@ -136,7 +136,7 @@
     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 @@
     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 @@
     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.

Modified: sandbox/trunk/setuptools/setuptools.txt
==============================================================================
--- sandbox/trunk/setuptools/setuptools.txt	(original)
+++ sandbox/trunk/setuptools/setuptools.txt	Thu Dec  1 02:18:03 2005
@@ -197,8 +197,8 @@
 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 @@
 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