More documentation enhancements.

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

EasyInstall.txt

@@ -28,11 +28,19 @@ Using "Easy Install"
 Installing "Easy Install"
 -------------------------
 
+If you are behind an NTLM-based firewall that prevents Python programs from
+accessing the net directly, you may wish to first install and use the `APS
+proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such firewalls
+in the same way that your web browser(s) do.
+
+If you do not have write access to your computer's ``site-packages`` directory,
+please also see the section below on `Non-Root Installation`_ for more detailed
+instructions on pre-configuring your system for the best usability with
+EasyInstall, then return here for the remaining steps.
+
 Download `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_, and
 run it; this will download and install the appropriate ``setuptools`` egg for
-your Python version.  (Note: if you do not have write access to your computer's
-``site-packages`` directory, please see the section below on `Non-Root
-Installation`_ for more detailed instructions.)
+your Python version.
 
 You may receive a message telling you about an obsolete version of
 setuptools being present; if so, you must be sure to delete it entirely, along

ez_setup.py

@@ -109,8 +109,7 @@ you may need to enable firewall access for this script first.
 I will start the download in %d seconds.
 ---------------------------------------------------------------------------""",
                     version, download_base, delay
-                )
-                from time import sleep; sleep(delay)
+                ); from time import sleep; sleep(delay)
             log.warn("Downloading %s", url)
             src = urllib2.urlopen(url)
             # Read/write all in one block, so we don't create a corrupt file

pkg_resources.txt

@@ -18,7 +18,8 @@ packages.
 Overview
 --------
 
-XXX TBD
+This section isn't written yet.  For now, please check out the extensive `API
+Reference`_ below.
 
 
 -----------------
@@ -43,6 +44,8 @@ This section isn't written yet.  Currently planned topics include::
         Extended Discovery and Installation
     Supporting Custom PEP 302 Implementations
 
+For now, please check out the extensive `API Reference`_ below.
+
 
 -------------
 API Reference

setuptools.txt

@@ -69,12 +69,21 @@ Developer's Guide
 Installing ``setuptools``
 =========================
 
-Download `ez_setup.py`_ and run it; this will download and install the
-appropriate egg for your Python version.  (Note: if you are behind
-an NTLM-based firewall that prevents Python programs from accessing the net
-directly, you may wish to install and use the `APS proxy server
-<http://ntlmaps.sf.net/>`_, which lets you get past such firewalls in the same
-way that your web browser(s) do.)
+If you are behind an NTLM-based firewall that prevents Python programs from
+accessing the net directly, you may wish to first install and use the `APS
+proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such firewalls
+in the same way that your web browser(s) do.
+
+If you do not have write access to your computer's ``site-packages`` directory,
+please also see the EasyInstall documentation on `Non-Root Installation`_ for
+more detailed instructions on pre-configuring your system for the best
+usability with setuptools and EasyInstall, then return here for the remaining
+steps.
+
+.. _Non-Root Installation: http://peak.telecommunity.com/DevCenter/EasyInstall#non-root-installation
+
+To install setuptools, first download `ez_setup.py`_ and run it; this will
+automatically download and install the appropriate egg for your Python version.
 
 .. _ez_setup.py: `bootstrap module`_
 
@@ -90,15 +99,18 @@ To get the in-development version of setuptools, run::
 
 You can then install it using the usual "setup.py install" incantation.
 
-Note that ``setuptools`` *must* be installed as an egg directory; it will not
+(Note that ``setuptools`` *must* be installed as an egg directory; it will not
 operate correctly otherwise.  If you are unable to install to a valid
-``site-packages`` directory (e.g. a "non-root install"), you will therefore
-need to manually add the setuptools egg to your ``PYTHONPATH``.  (You won't
-need to do this for every egg you install, because the ``pkg_resources`` module
-can automatically find eggs and add them to ``sys.path`` at runtime.  It's just
-that the ``setuptools`` egg contains ``pkg_resources`` and therefore has to
-be manually bootstrapped if you can't install it to a ``site-packages``
-directory.)
+``site-packages`` directory (e.g. a "non-root install" that doesn't conform
+to the `Non-Root Installation`_ procedure), you will therefore need to manually
+add the setuptools egg to your ``PYTHONPATH``.  You won't need to do this for
+every egg you install, because the ``pkg_resources`` module can automatically
+find eggs and add them to ``sys.path`` at runtime.  It's just that the
+``setuptools`` egg contains the ``pkg_resources`` runtime, and therefore has to
+be manually bootstrapped if you can't install it to a valid ``site-packages``
+directory.  However, if you are installing as root or you followed the
+`Non-Root Installation`_ procedure, you shouldn't have to worry about any of
+this.)
 
 
 Basic Use