Moved some text into separate files and mande a number of other

editorial changes.

src/ZEO/README

@@ -3,7 +3,7 @@ Zope Enterprize Objects, ZEO 0.2
   Put this package (the ZEO directory, without any wrapping directory
   included in a distribution) in your Zope lib/python.
 
-  Note -- This release of ZEO requires Zope 2.2 or a CVS checkout
+  Note -- This release of ZEO requires Zope 2.2.2 or a CVS checkout
     of Zope. See 'CHANGES.txt' for details.
 
   You also need to symbolically link (or copy) ZServer to lib/python::
@@ -20,144 +20,58 @@ Zope Enterprize Objects, ZEO 0.2
   This is necessary because ZEO uses a (relatively) new
   cPickle feature that wasn't included in Python 1.5.2.
 
-  To start the storage server, go to your Zope install directory and::
+  Starting (and configuring) the ZEO Server
 
-    python lib/python/ZEO/start.py -p port_number
+    To start the storage server, go to your Zope install directory and::
 
-  (Run start without arguments to see options.)
+      python lib/python/ZEO/start.py -p port_number
 
-  Of course, the server and the client don't have to be on the same
-  machine.
+    (Run start without arguments to see options.)
 
-  If the server and client *are* on the same machine, then you can use 
-  a Unix domain socket::
+    Of course, the server and the client don't have to be on the same
+    machine.
 
-    python lib/python/ZEO/start.py -U filename
+    If the server and client *are* on the same machine, then you can use 
+    a Unix domain socket::
 
-  To get Zope to use the server, create a custom_zodb module,
-  custom_zodb.py, in your Zope install directory, so that Zope uses a
-  ClientStorage::
+      python lib/python/ZEO/start.py -U filename
 
-    import ZEO.ClientStorage
-    Storage=ZEO.ClientStorage.ClientStorage(('',port_number))
+    The start script provides a number of options not documented here.
+    See doc/start.txt for more information.
+        
+  Running Zope as a ZEO client
 
-  (See the custom_zodb.py.dist in the same ZEO directory as this
-  README for an example.)
+    To get Zope to use the server, create a custom_zodb module,
+    custom_zodb.py, in your Zope install directory, so that Zope uses a
+    ClientStorage::
 
-  You can specify a host name (rather than '') if you want.  The port
-  number is, of course, the port number used to start the storage
-  server.  The ClientStorage 'async' switch tells the client to switch
-  itself to async mode (if and) when the medusa asyncore main loop is
-  called.
-
-  You can also give the name of a Unix domain socket file::
-
-    import ZEO.ClientStorage
-    Storage=ZEO.ClientStorage.ClientStorage(filename)
-
-  If you want a persistent client cache which retains cache contents
-  across ClientStorage restarts, you need to define the environment
-  variable, ZEO_CLIENT, to a unique name for the client.  This is
-  needed so that unique cache name files can be computed.  Otherwise,
-  the client cache is stored in temporary files which are removed when
-  the ClientStorage shuts down.  For example, to start two Zope
-  processes with unique caches, use something like:
-
-    python z2.py -P8700 ZEO_CLIENT=8700
-    python z2.py -P8800 ZEO_CLIENT=8800
-
-  The ClientStorage constructor provides a number of additional
-  options (arguments):
-
-    storage -- The name of the storage to connect to.  
-
-    cache_size -- The number of bytes to allow for the client cache.
-         The default is 20,000,000.
-    
-    name -- The name to use for the storage. This will be shown in
-         Zope's control panel. The default name is a representation of
-         the connection information.
-
-    debug -- If this is provided, it should be a non-empty string. It
-         indicates that client should log tracing and debugging
-         information, using zLOG.
-
-    var -- The directory in which persistent cache files should be
-         written. If this option is provided, it is unnecessary to 
-         set INSTANCE_HOME in __builtins__.
-
-  Serving custom storages or multiple storages with the storage server
-
-    The Storage server can host multiple storages and can
-    host any kind of storage. Each storage has a unique storage
-    name.  By default, the ZEO start.py script serves a 
-    standard FileStorage with the name '1'.
-
-    You can control what storages are served by creating a Python
-    file containing definitions for the storages and using the '-S'
-    option to the start.py script to indicate the storage
-    to be served. The form of the -S option is::
-
-       -Sstorage_name=module_path:attribute_name
-
-    Where:
-
-	storage_name -- is the storage name used in the ZEO protocol.
-	   This is the name that you give as the optional
-	   'storage' keyword argument to the ClientStorage constructor.
-
-	module_path -- This is the path to a Python module
-	   that defines the storage object(s) to be served.
-	   The module path should ommit the prefix (e.g. '.py').
-
-	attribute_name -- This is the name to which the storage object
-	  is assigned in the module.
-
-
-    Consider the following example. I want to serve a FileStorage
-    in read-only mode, which I define in the module file 
-    /stores/fs.py::
-
-      import ZODB.FileStorage
-      Storage=FileStorage('/stores/fs1.fs', read_only=1)
-
-    I then start start.py with the argument::
-
-      python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-        -S 1=/stores/fs:Storage
+      import ZEO.ClientStorage
+      Storage=ZEO.ClientStorage.ClientStorage(('',port_number))
 
-    This option says to serve storage '1'. Storage '1' is
-    found in attribute 'Storage' from the module
-    '/stores/fs'.
+    (See the misc/custom_zodb.py for an example.)
 
-    Now consider a more complicated example. I want to serve the storage
-    from the previous example. I also want to serve two Oracle
-    storages that are defined in the file '/stores/oracle.py'::
+    You can specify a host name (rather than '') if you want.  The port
+    number is, of course, the port number used to start the storage
+    server.
 
-      import DCOracle, DCOracleStorage
-      system=DCOracleStorage.DCOracleStorage(
-        lambda : DCOracle.Connect('system/manager@spamservice')
-        )
-      scott=DCOracleStorage.DCOracleStorage(
-        lambda : DCOracle.Connect('scott/tiger@spamservice')
-        )
+    You can also give the name of a Unix domain socket file::
 
-    I simply need to include three -S options::
+      import ZEO.ClientStorage
+      Storage=ZEO.ClientStorage.ClientStorage(filename)
 
-      python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-        -Ssystem=/stores/oracle:system                 \
-        -Sscott=/stores/oracle:scott                   \
-        -S1=/stores/fs:Storage
+    There are a number of configuration options available for the
+    ClientStorage. See doc/ClientStorage.txt for details.
 
-    In this case, we made the storage and attribute name the
-    same. To connect to the 'system' or 'scott' storage, we
-    need to specify the storage in the ClientStorage constructor, as
-    in::
+    If you want a persistent client cache which retains cache contents
+    across ClientStorage restarts, you need to define the environment
+    variable, ZEO_CLIENT, to a unique name for the client.  This is
+    needed so that unique cache name files can be computed.  Otherwise,
+    the client cache is stored in temporary files which are removed when
+    the ClientStorage shuts down.  For example, to start two Zope
+    processes with unique caches, use something like:
 
-      import ZEO.ClientStorage
-      Storage=ZEO.ClientStorage.ClientStorage(
-          '/xxx/var/zeo.sock', storage='scott')
-   
+      python z2.py -P8700 ZEO_CLIENT=8700
+      python z2.py -P8800 ZEO_CLIENT=8800
 
   Zope product installation
 
@@ -169,10 +83,18 @@ Zope Enterprize Objects, ZEO 0.2
 
     Starting in Zope 2.2, Zope will not modify the Zope database
     during product installation if the environment variable ZEO_CLIENT
-    is set. For this reason, Zope must be started without the
-    ZEO_CLIENT variable set to install new disk-based products. Of
-    course, the disk-based products should be consistent accross ZEO
-    Client installations.
+    is set. 
+
+    Normally, Zope ZEO clients should be run with ZEO_CLIENT set so
+    that product initialization is not performed.
+
+    If you do install new Zope products, then you need to take a
+    special step to cause the new products to be properly registered
+    in the database.  The easiest way to do this is to start Zope
+    once without ZEO_CLIENT set.
+
+    The interaction between ZEO and Zope product installation is
+    unfortunate.  In the future, this interaction will be removed by 
 
   Notes for non Zope users