Improve install docs and clarify in-place vs. traditional build.

doc/INSTALL.txt

-
-*** These instructions pertain to the new-install-branch! ***
-
-
 Building and installing Zope from source
 ----------------------------------------
 
-  This document describes building and installing Zope on UNIX and
-  Linux.
+  Welcome to Zope!  This document describes building and installing
+  Zope on UNIX and Linux.
 
 System requirements when building from source
 
    bash or another Bourne shell variant
-   Python 2.2.2 or later installed somewhere in the system PATH
+   Python 2.2.3 or later installed somewhere in the system PATH
    GNU make
    A C compiler (gcc recommended)
 
-Quick Start
+Recommendations
+
+  - You are recommended to build and install Zope as a non-root user.
+
+Building Zope
+
+  To build Zope, run the conventional UNIX build sequence from within
+  the Zope source tree::
+
+    ./configure --prefix=/where/to/install/zope
+    make
+
+  If you do not specify a '--prefix' option, during a later step, Zope
+  will be installed into a default location.
+
+  If the configure script cannot find a suitable Python interpreter
+  for use with Zope, it will complain with an informative error
+  message.  If this happens, you may use the '--with-python'
+  command-line option to 'configure' to specify which Python
+  interpreter to use.  Run './configure --help' to see other
+  command-line options available via the configure script.
+
+  Optional:  Building and Installing Zope 'In-Place'
 
-  It is best to install Zope as a non-root user.
+    Older versions of Zope were typically run directly from the
+    'source' directory itself.  This is useful for development
+    purposes.  You can reobtain that behavior by performing the
+    following sequence of commands within a Zope source directory:
 
-  If you are impatient, the following commands should get you up and
-  running on any UNIX that meet the system requirements::
+      ./configure
+      make instance
 
-    $ gunzip -c Zope-2.7.X-src.tar.gz | xar xvf
-    $ cd Zope-2.7.X
-    $ ./configure --prefix=/where/to/install/zope
-    $ make
-    $ make instance
+    This set of commands builds binary files and creates the files
+    necessary for a Zope instance to be run directly within the build
+    directory (e.g. 'in-place').  You may now start Zope by running::
 
-  These commands locate an appropriate version of Python, build Zope,
-  and create a usable Zope "instance" in the directory in which the
-  software was un-tarred.  The last of these commands will prompt you
-  to provide a user name and password for an administrator's account.
+      ./bin/runzope
 
-  You can now start Zope by running::
+  Optional:  Building Zope Using The "Clean-Source-Tree" Method
 
-    $ ./bin/runzope
+    You can run the 'configure' command from outside of the Zope
+    source tree.  If you do so, the makefile will be written to your
+    current directory.  The files generated by the build process (via
+    'make') will be written to the directory from which you run
+    'configure'.  You can then use 'make install' to install these
+    files to their canonical locations.  This feature is to support
+    source locations which are not writable.
+
+Installing Zope
+
+  To install Zope to the place you've specified via the '--prefix'
+  option (or to the default location if you didn't specify a prefix),
+  type::
+
+    make install
+
+Creating a Zope Instance Home
+
+  Once you've performed the install step, to begin actually using
+  Zope, you will need to create an "instance home", which is a
+  directory that contains configuration and data for a Zope server
+  process.  The instance home is created using the 'mkzopeinstance'
+  script::
+
+    /where/to/install/zope/bin/mkzopeinstance /location/of/zope/instance
+
+  You will be asked to provide a user name and password for an
+  administrator's account during the 'mkzopeinstance'.  Command-line
+  options to 'mkzopeinstance' are available, and can be investigated
+  by running 'mkzopeinstance --help'.
+
+Starting Zope
+
+  Once an instance home has been created, the Zope server can now be
+  started using this command:
+
+    /location/of/zope/instance/bin/runzope
 
   If you get errors indicating that addresses are in use, then you
   will have to supply arguments to runzope to change the ports used
   for HTTP or FTP. The default HTTP and FTP ports used by Zope are
   8080 and 8021 respectively. You can change the ports used by
   specifying the "port-base" parameter to runzope.  For example, to
-  run Zope on ports 9080 and 9021:
+  run Zope on ports 9080 and 9021::
+
+    ./bin/runzope -X port-base=1000
+
+  There is also an interactive Zope command shell named 'zopectl' that
+  may be invoked by running 'bin/zopectl'.  By default, 'zopectl
+  start' will start a background process that manages Zope and
+  'zopectl stop' will stop the background process.
 
-    $ ./bin/runzope -X port-base=1000
+Logging In To Zope
 
-  You can then connect to Zope by directing your browser to::
+  Once you've started Zope, you can then connect to the Zope webserver
+  by directing your browser to::
 
      http://yourhost:8080/manage
 
@@ -70,61 +130,29 @@ Quick Start
 
     http://www.zope.org/Documentation/Books/ZopeBook
 
-  Have fun!
-
-Building Zope
-
-  If you want to try out Zope in a more permanent fashion, then run the
-  conventional UNIX build sequence::
-
-    ./configure --prefix /where/to/install/zope
-    make
-    make install
-
-  Next, you need to create an "instance home", which contains
-  configuration and data for a Zope server process:
-
-    /where/to/install/zope/bin/mkzopeinstance /location/of/zope/instance
+Integrating Zope With An Existing Webserver
 
-  The Zope server can now be started using this command:
-
-    /location/of/zope/instance/bin/runzope
-
-  Notes
-
-    * You need to be using Python 2.2.2 or later to run the build
-      scripts; the ./configure script will attempt to locate the best
-      available interpreter.  All future invocations of Zope will use
-      that Python interpreter.
-
-    * The Python you run Zope with *must* have threads compiled in,
-      which is the case for a vanilla build.  Warning: Zope will not
-      run with a Python version that uses libpth.  You *must* use
-      libpthread.
+  Zope doesn't require any existing webserver to run, but you can
+  integrate it with other webservers as necessary.  See the
+  WEBSERVERS.txt file for more information about configuring Zope with
+  an existing web server.  There is also information about integrating
+  Zope with existing webservers on the Zope.org website.
 
-    * To build Python extensions you need to have Python configuration
-      information available. If your Python comes from an RPM you may
-      need the python-devel (or python-dev) package installed too. If
-      you built Python from source all the configuration information
-      should already be available.
+Troubleshooting
 
-    * If you just want to use Zope components it's not necessary to
-      build Zope but it's a good idea since it will compile Python C
-      extensions for you.
+  - This version of Zope requires Python 2.2.3 or better.
 
-    * See CHANGES.txt for important notes on this version of Zope.
+  - The Python you run Zope with *must* have threads compiled in,
+    which is the case for a vanilla build.  Warning: Zope will not run
+    with a Python version that uses libpth.  You *must* use
+    libpthread.
 
-    * You can run the 'configure' command outside of the Zope source
-      tree.  If you do so, the makefile and the files generated by the
-      build process will be written to the directory from which you
-      run 'configure'.  You can then use 'make install' to install these
-      files to their canonical locations.  This is to support
-      source locations which are not writable.
+  - To build Python extensions you need to have Python configuration
+    information available. If your Python comes from an RPM you may
+    need the python-devel (or python-dev) package installed too. If
+    you built Python from source all the configuration information
+    should already be available.
 
-Integrating Zope with an existing webserver
+  - See CHANGES.txt for important notes on this version of Zope.
 
-  Zope doesn't require any existing webserver to run, but you can
-  integrate it with other webservers as necessary.  See the
-  WEBSERVERS.txt file for more information about configuring Zope with
-  an existing web server.