Umproved documentation to make html generation better.

README.txt

 Zope Buildout
 =============
 
+.. contents::
+
 The Zope Buildout project provides support for creating applications,
-especially Pyton applications.  It provides tools for assembling
+especially Python applications.  It provides tools for assembling
 applications from multiple parts, Python or otherwise.  An application
 may actually contain multiple programs, processes, and configuration
 settings.
@@ -14,7 +16,7 @@ prototype of the buildout system. We have a Zope application consisting of:
 
 - 4 ZEO servers
 
-- An ldap server
+- An LDAP server
 
 - Cache-invalidation and Mail delivery servers
 
@@ -85,13 +87,100 @@ Buildouts are defined using configuration files.  These files are
 based on the Python ConfigParser module with some variable-definition
 and substitution extensions.  
 
+Installation
+------------
+
+There are two ways to install zc,buildout
+
+1. Install it as an egg using `easy_install
+   <http://peak.telecommunity.com/DevCenter/EasyInstall>`_ into a
+   Python instaallation. Then just use the buildout script from your
+   Python bin or Scripts directory.
+
+2. Use the `bootstrap script
+   <http://dev.zope.org/Buildout/bootstrap.py>`_ to install setuptools
+   and the buildout software into your buildout.  Typically, you'll
+   check the bootstrap script into your project so that, whenever you
+   checkout your project, you can turn it into a buildout by just
+   running the bootstrap script.
+
+More information
+----------------
+
 The detailed documentation for the various parts of buildout can be
 found in the following files:
 
-buildout.txt
+`buildout.txt <http://dev.zope.org/Buildout/buildout.html>`_
    Describes how to define and run buildouts.  It also describes how
    to write recipes.
 
-easy_install.txt
+`easy_install.txt <http://dev.zope.org/Buildout/easy_install.html>`_
    Describes an Python APIs for invoking easy_install for generation
    of scripts with paths baked into them.
+
+Download
+--------
+
+You can download zc.buildout and many buildout recipes from the
+`Python Package Index <http://www.python.org/pypi>`_.
+
+Recipes
+-------
+
+Existing recipes include:
+
+`zc.recipe.egg <http://dev.zope.org/Buildout/egg.html>`_
+   The egg recipe installes one or more eggs, with their
+   dependencies.  It installs their console-script entry points with
+   the needed eggs included in their paths.
+
+`zc.recipe.testrunner <http://dev.zope.org/Buildout/testrunner.html>`_
+   The testrunner egg installs creates a test runner script for one or
+   more eggs.
+
+`zc.recipe.zope3checkout <http://dev.zope.org/Buildout/zope3checkout.html>`_
+   The zope3checkout recipe installs a Zope 3 checkout into a
+   buildout.
+
+`zc.recipe.zope3instance <http://dev.zope.org/Buildout/zope3instance.html>`_
+   The zope3instance recipe sets up a Zope 3 instance.
+
+`zc.recipe.filestorage <http://dev.zope.org/Buildout/filestorage.html>`_
+   The filestorage recipe sets up a ZODB file storage for use in a
+   Zope 3 instance creayed by the zope3instance recipe.
+
+Buildout examples
+-----------------
+
+Some simple buildout examples:
+
+`The zc.buildout project <http://svn.zope.org/zc.buildout/trunk>`_
+   This is the project for the buildout software itself, which is
+   developed as a buildout. 
+
+`The zc sharing project <http://svn.zope.org/zc.sharing/trunk>`_
+   This project illistrates using the buildout software with Zope 3.
+   Note that the bootstrap.py file is checked in so that a buildout
+   can be made when the project is checked out.  The buildout.cfg
+   specified everything needed to create a Zope 3 installation with
+   the zc.sharing package installed in development mode.
+
+
+Status
+------
+
+The buildout system is under active development. Some near term
+priorities include:
+
+- Better error reporing
+
+- Windows support
+
+- Handling of egg extras
+
+- More recipes
+
+Questions
+---------
+
+You can send questions to jim@zope.com.