ReSTify the installation docs, and note use of buildout vs. CMMI.

doc/INSTALL.txt

+========================================
 Building and installing Zope from source
-----------------------------------------
+========================================
 
-  Welcome to Zope!  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.
 
-  See WINDOWS.txt for information about Windows.  See the PLATFORMS
-  directory for notes about various other platforms.
+See ``doc/WINDOWS.txt`` for information about Windows.  See the
+``doc/PLATFORMS`` directory for notes about various other platforms.
 
-System requirements when building from source
-
-   * bash or another Bourne shell variant
-
-   * Python 2.4.2 or later installed somewhere in the system PATH
-     (Python 2.5 is not supported)
 
-   * GNU make
+Prerequisites
+-------------
 
-   * A C compiler (gcc recommended)
-
-Recommendations
+System requirements when building from source
 
-  - You are recommended to build and install Zope as a non-root user.
+- A supported version of Python, including the development support if
+  installed from system-level packages.  Supported versions include::
 
-Building Zope
+  o 2.4.x, (x >= 4)
 
-  To build Zope, run the conventional UNIX build sequence from within
-  the Zope source tree::
+  o 2.5.x
+  
+- Zope needs the Python ``zlib`` module to be importable.  If you are
+  building your own Python from source, please be sure that you have the
+  headers installed which correspond to your system's ``zlib``.
 
-    ./configure --prefix=/where/to/install/zope
-    make
+- A C compiler capable of building extension modules for your Python
+  (gcc recommended).
 
-  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.
+Building Zope
+-------------
 
-  Optional:  Building and Installing Zope 'In-Place' (SVN checkouts only)
+Zope is built using the ``zc.buildout`` library, which needs to be
+"boostrapped" with your Python version.  E.g.::
 
-    Older versions of Zope were typically run directly from the
-    'source' directory itself.  This is useful for development
-    purposes.  You can regain that behavior by performing the
-    following sequence of commands within a Zope source directory:
+  $ cd /path/to/zope
+  $ /path/to/your/python bootstrap/bootstrap.py
 
-      ./configure
-      make instance
+The boostrap script creates a ``buildout`` script in ``bin``;  run this
+script to finish building Zope::
 
-    This command also creates an administrative user with the
-    specified username and password.
+  $ bin/buildout
 
-    WARNING: "make instance" doesn't work on FreeBSD 5.0 and
-    presumably other platforms. You should either use GNU make
-    (gmake instance), or use "make install" instead.
 
-    Making an "In-Place" instance builds the 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 start
-    Zope by running::
+Creating a Zope Instance
+------------------------
 
-      ./bin/zopectl start
+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::
 
-    See ./log/event.log for any output which may happen during
-    start of Zope. If anything goes wrong you will see there.
+  $ /bin/mkzopeinstance
 
-    If you use
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``.  To see the available
+ommand-line options, run the script with the ``--help`` option::
 
-      ./bin/zopectl fg
+  $ bin/mkzopeinstance --help
 
-    instead, the output is generated to the screen. In this case
-    Zope does not detach from terminal.
 
-  Optional:  Building Zope Using The "Clean-Source-Tree" Method
+Starting Zope as a Daemon
+-------------------------
 
-    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.
+Once an instance home has been created, the Zope server can now be
+started using this command::
 
-Installing Zope
+  $ /path/to/zope/instance/bin/zopectl start
 
-  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::
+During start, zope emits log messages into ./log/event.log
+You can examine it with the usual tools (cat, more, tail)
+and see if there are any errors preventing zope from starting.
 
-    make install
 
-Creating a Zope Instance Home
+Running Zope in the Foreground
+------------------------------
 
-  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.py'
-  script::
+By default, ``zopectl start`` will start a background process (a
+"daemon) that manages Zope.  ``zopectl stop`` will stop the background
+process.  To run Zope without detaching from the console, use the ``fg``
+command (short for ``foreground``)::
 
-    /where/to/install/zope/bin/mkzopeinstance.py
+  $ /path/to/zope/instance/bin/zopectl fg
 
-  You will be asked to provide a user name and password for an
-  administrator's account during 'mkzopeinstance'.  Command-line
-  options to 'mkzopeinstance' are available, and can be investigated
-  by running 'mkzopeinstance.py --help'.
+In this mode, Zope emits its log messages to the console, and does not
+detach from terminal.
 
-Starting Zope
 
-  Once an instance home has been created, the Zope server can now be
-  started using this command:
+Configuring Zope
+----------------
 
-    /location/of/zope/instance/bin/zopectl start
+Your Zope instance is configured through a file, either found by
+default::
 
-  During start, zope emits log messages into ./log/event.log
-  You can examine it with the usual tools (cat, more, tail)
-  and see if there are any errors preventing zope from starting.
+  $ /path/to/zope/instance/bin/zopectl show
+  ...
+  Config file:  /path/to/zope/instance/etc/zope.conf
 
-    /location/of/zope/instance/bin/zopectl fg
+or passed explicitly on the commandline::
 
-  can be used to instead output these messages to the console. This
-  way zope does not detach from terminal.
+  $ /path/to/zope/instance/bin/zopectl -c /tmp/other.conf show
+  ...
+  Config file:  /tmp/other.conf
 
-  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
-  editing ./etc/zope.conf apropriately.
+When starting Zope, if you see errors indicating that an address is 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
+editing ./etc/zope.conf apropriately.
 
-  The section usually is like this:
+The section in the configuration file looks like this::
 
   <http-server>
     # valid keys are "address" and "force-connection-close"
@@ -137,70 +119,76 @@ Starting Zope
     # force-connection-close on
   </http-server>
 
-  address can just be a port number as shown, but also a host:port
-  pair to bind to a specific interface only.
+The address can just be a port number as shown, or a  host:port
+pair to bind only to a specific interface.
+
+
+Integrating with System Startup
+-------------------------------
 
-  zopectl can be linked as rc-script in the usual start directories
-  on linux or other system V unix variants.
+zopectl can be linked as rc-script in the usual start directories
+on linux or other System V unix variants.
 
-  You can use zopectl interactively as a command shell by just
-  calling it w/o any arguments. Try help there and help <command>
-  to find out about additionally commands of zopectl. These commands
-  work also on command line.
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
 
-  By default, 'zopectl start' will start a background process that
-  manages Zope and 'zopectl stop' will stop the background process.
 
 Logging In To Zope
+------------------
 
-  Once you've started Zope, you can then connect to the Zope webserver
-  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
+  http://yourhost:8080/manage
 
-  .. where 'yourhost' is the DNS name or IP address of the machine
-  running Zope.  If you changed the HTTP port as described, use a port
-  number of 8080 + the port-base value.
+.. where 'yourhost' is the DNS name or IP address of the machine
+running Zope.  If you changed the HTTP port as described, use the port
+you configured.
 
-  You will be prompted for a user name and password. Use the user name
-  and password you provided in response to the prompts issued during
-  the "make instance" process.
+You will be prompted for a user name and password. Use the user name
+and password you provided in response to the prompts issued during
+the "make instance" process.
 
-  Now you're off and running! You should be looking at the Zope
-  management screen which is divided into two frames. On the left you
-  can navigate between Zope objects and on the right you can edit them
-  by selecting different management functions with the tabs at the top
-  of the frame.
+Now you're off and running! You should be looking at the Zope
+management screen which is divided into two frames. On the left you
+can navigate between Zope objects and on the right you can edit them
+by selecting different management functions with the tabs at the top
+of the frame.
 
-  If you haven't used Zope before, you should head to the Zope web
-  site and read some documentation. The Zope Book is a good place to
-  start. You can access the Zope Book at:
+If you haven't used Zope before, you should head to the Zope web
+site and read some documentation. The Zope Book is a good place to
+start. You can access the Zope Book at:
 
-    http://www.zope.org/Documentation/Books/ZopeBook
+http://www.zope.org/Documentation/Books/ZopeBook
 
 Integrating Zope With An Existing Webserver
+--------------------------------------------
 
-  Zope doesn't require any existing webserver to run, but you can
-  integrate it with other webservers as necessary.  See the
-  WEBSERVER.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.
+Zope doesn't require any existing webserver to run, but you can
+integrate it with other webservers as necessary.  See the
+``doc/WEBSERVER.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.
 
 Troubleshooting
+---------------
 
-  - This version of Zope requires Python 2.4.1 or better.
-
-  - 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.
-
-  - 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.
+- This version of Zope requires Python 2.4.4 or better, including
+  2.5.x.  It may run with Python 2.6.x, although this configuration
+  is not supported in this version of Zope.  It will *not* run with
+  Python 3.x.
 
-  - 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``.
 
+- 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.
 
+- See ``doc/CHANGES.txt`` for important notes on this version of Zope.