added documentation files

doc/ZEO/ClientCache.txt

+ZEO Client Cache
+
+  The Client cache provides a disk based cache for each ZEO client.
+  The client cache allows reads to be done from local disk rather than
+  by remote access to the storage server.
+
+  The cache may be persistent or transient. If the cache is
+  persistent, then the cache files are retained for use after process
+  restarts. A non-persistent cache uses temporary files that are
+  removed when the client storage is closed.
+
+  The client cache is managed as two files. The cache manager
+  endeavors to maintain the two files at sizes less than or equal to
+  one half the cache size.  One of the cache files is designated the
+  "current" cache file. The other cache file is designated the "old"
+  cache file, if it exists.  All writes are done to the current cache
+  files.  When transactions are committed on the client, transactions
+  are not split between cache files. Large transactions may cause
+  cache files to be larger than one half the target cache size.
+
+  The life of the cache is as follows:
+
+  - When the cache is created, the first of the two cache files is
+    created and designated the "current" cache file.
+
+  - Cache records are written to the cache file, either as
+    transactions commit locally, or as data are loaded from the
+    server.
+
+  - When the cache file size exceeds one half the cache size, the
+    second cache file is created and designated the "current" cache
+    file.  The first cache file becomes the "old" cache file.
+
+  - Cache records are written to the new current cache file, either as
+    transactions commit locally, or as data are loaded from the
+    server.
+
+  - When the current cache file size exceeds one half the cache size, the
+    first cache file is recreated and designated the "current" cache
+    file.  The second cache file becomes the "old" cache file.
+
+  and so on.
+
+  Persistent cache files are created in the directory named in the
+  'var' argument to the ClientStorage (see ClientStorage.txt) or in
+  the 'var' subdirectory of the directory given by the INSTANCE_HOME
+  builtin (created by Zope), or in the current working directory.
+  Persistent cache files have names of the form::
+
+    cstorage-client-n.zec
+
+  where:
+
+    storage -- the storage name
+
+    client -- the client name, as given by the 'ZEO_CLIENT' environment
+      variable or the 'client' argument provided when creating a client
+      storage.
+
+    n -- '0' for the first cache file and '1' for the second. 
+
+  For example, the second cache file for storage 'spam' and client 8881
+  would be named 'cspam-8881-1.zec'.

doc/ZEO/ClientStorage.txt

+ClientStorage
+
+  The ClientStorage is a ZODB storage implementation that provides
+  access to data served bt a ZEO server.  To use a ClientStorage,
+  create the SlientStorage and configure your application to use
+  it. To configure Zope to use a ClientStorage, create the ClientStorage
+  and and assign it to the 'Storage' variable in a 'custom_zodb'
+  module (typically a Python file, with a '.py' suffix) in the
+  instance home of your Zope installation.
+
+  Creating a ClientStorage
+
+    At a minimum, a client storage requires an argument (named
+    connection) giving connection information. This argument should be
+    a string, specifying a unix-domain socket file name, or a tuple
+    consisting of a host and port. The host should be a string host
+    name or IP number. The port should be a numeric port number.
+
+    The ClientStorage constructor provides a number of additional
+    options (arguments). The full list of arguments is:
+
+    connection -- Connection information.
+
+     This argument is either a string containing a socket file name
+     or a tuple consisting of a string host name or ip number and an
+     integer port.
+
+    storage -- The name of the storage to connect to.  
+
+      A ZEO storage server can serve multiple storages.  Each
+      storage has a name, which is configured on the server.  The
+      server adminstrator should be able to provide this name. The
+      default name for both the server and client is '1'.
+
+    cache_size -- The number of bytes to allow for the client cache.
+      The default is 20,000,000.
+
+      For more information on client caches, see ClientCache.txt.
+
+    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.
+
+    client -- The name to be used for the persistent client cache files.
+
+      This parameter can be used instead of or to override the
+      ZEO_CLIENT environment variable. It is generally better to use
+      the environment variable because it's easier to change
+      environment variables that it is to change Python code for
+      creating the storage.
+
+      Also note that, if you are using Zope, the ZEO_CLIENT
+      environment variable effects whether products are initialized.
+
+      For more information on client cache files, see ClientCache.txt.
+
+    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__. 
+
+      For more information on client cache files, see ClientCache.txt.
+
+    min_disconnect_poll -- The minimum number of seconds to wait before
+      retrying connections after connection failure.
+
+      When trying to make a connection, if the connection fails, the
+      ZEO client will wait a period of time before retrying the
+      connection.  The amount of time waited starts at the value given
+      by 'min_disconnect_poll' and doubles on each attempt, but never
+      exceeds the number of seconds given by 'max_disconnect_poll'.
+
+      The default is 5 seconds.
+
+    max_disconnect_poll  -- The maximum number of seconds to wait before
+      retrying connections after connection failure.
+
+      See min_disconnect_poll.
+
+      The default is 300 seconds.
+
+    wait_for_server_on_starup -- Indicate whether the ClientStorage
+      should block waiting for a storage server connection, or whether
+      it should proceed, satisfying reads from the client cache.

doc/ZEO/start.txt

+The ZEO Server start script, start.py
+
+  ZEO provides a Python script for starting the ZEO server.  The ZEO
+  server is implemented as a Python class and could be used with other
+  main programs, however, a simple ZEO server is provided for convenience.
+
+  Basic usage
+
+    To start the storage server, go to your Zope install directory and::
+
+      python lib/python/ZEO/start.py -p port_number
+
+    (Run start without arguments to see options.)
+
+    Of course, the server and the client don't have to be on the same
+    machine.
+
+    If the server and client *are* on the same machine, then you can use 
+    a Unix domain socket::
+
+      python lib/python/ZEO/start.py -U filename
+
+  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.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
+
+    This option says to serve storage '1'. Storage '1' is
+    found in attribute 'Storage' from the module
+    '/stores/fs'.
+
+    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'::
+
+      import DCOracle, DCOracleStorage
+      system=DCOracleStorage.DCOracleStorage(
+        lambda : DCOracle.Connect('system/manager@spamservice')
+        )
+      scott=DCOracleStorage.DCOracleStorage(
+        lambda : DCOracle.Connect('scott/tiger@spamservice')
+        )
+
+    I simply need to include three -S options::
+
+      python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
+        -Ssystem=/stores/oracle:system                 \
+        -Sscott=/stores/oracle:scott                   \
+        -S1=/stores/fs:Storage
+
+    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::
+
+      import ZEO.ClientStorage
+      Storage=ZEO.ClientStorage.ClientStorage(
+          '/xxx/var/zeo.sock', storage='scott')
+
+  Options
+
+    The ZEO server start script is run with one or more command line
+    options. An optional FileStorage file name may be provided after the
+    options. The options are as follows:
+
+     -D -- Run in debug mode
+
+	In debug mode, the process is not run in the background
+	and detailed debugging information is logged. 
+
+	Note that to actually log this information, you need to
+	configure logging to include very low-severity (< -300) log
+	entries. For example, to configure the stupid logger to log
+	these messages, set the environment veriable
+	'STUPID_LOG_SEVERITY' to -999.
+
+     -U -- Unix-domain socket file to listen on
+
+	If you want to accept connections on a Unix domain socket, then
+	use this option to specify the socket file name.
+
+     -u username or uid number
+
+       The username to run the ZEO server as. You may want to run
+       the ZEO server as 'zope' or some other user with limited
+       resouces. The only works under Unix, and if ZServer is
+       started by root.
+
+       If the server *is* started as root, the 'nobody' user if this
+       option isn't used.
+
+     -p port -- port to listen on
+
+       Use this option together with the '-h' option to specify a host
+       and port to listen on.
+
+     -h adddress -- host address to listen on
+
+       Use this option together with the '-p' option to specify a host
+       and port to listen on.
+
+     -s -- Don't use zdeamon
+
+       This option has no effect on Unix.
+
+     -S storage_name=module_path:attr_name -- A storage specification
+
+	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').
+
+	  attr_name -- This is the name to which the storage object
+	    is assigned in the module.
+
+
+