Copy a bunch of files from the ZODB3/Doc directory, losing history.

trunk/doc/ACKS

+Acknowledgments
+---------------
+
+This file lists people who have contribute code, bug fixes, ideas, and
+other support for ZODB.  Alas it is probably not complete.
+
+Anthony Baxter
+John Belmonte
+Johan Dahlin
+Toby Dickenson
+Fred L. Drake, Jr.
+Casey Duncan
+Jon Dyte
+Jim Fulton
+Florent Guillaume
+Shane Hathaway
+Nicholas Henke
+Jeremy Hylton
+Matt Kromer
+Andrew Kuchling
+Andreas Jung
+Brian Lloyd
+Ken Manheimer
+Dieter Maurer
+Chris McDonough
+Tim Peters
+Chris Petrilli
+Christian Reis
+Guido van Rossum
+Neil Schemenauer
+Tres Seaver
+Sidnei da Silva
+Evan Simpson
+Jens Vagelpohl
+Greg Ward
+Barry Warsaw
+Chris Withers

trunk/doc/Makefile

+MKHOWTO=mkhowto
+
+MKHTML=$(MKHOWTO) --html --iconserver=. --split=4 --dvips-safe
+
+ZODBTEX = guide/gfdl.tex guide/introduction.tex guide/modules.tex \
+	  guide/prog-zodb.tex guide/storages.tex guide/transactions.tex \
+	  guide/zeo.tex guide/zodb.tex 
+
+default: pdf
+all:	 pdf ps html
+
+pdf:	storage.pdf zodb.pdf
+ps:	storage.ps zodb.ps
+
+html:	storage/storage.html zodb/zodb.html
+
+storage.pdf: storage.tex
+	$(MKHOWTO) --pdf $<
+
+storage.ps: storage.tex
+	$(MKHOWTO) --ps $<
+
+storage/storage.html: storage.tex
+	$(MKHTML) storage.tex
+
+zodb.pdf: $(ZODBTEX)
+	$(MKHOWTO) --pdf guide/zodb.tex
+
+zodb.ps: $(ZODBTEX)
+	$(MKHOWTO) --ps guide/zodb.tex
+
+zodb/zodb.html: $(ZODBTEX)
+	$(MKHTML) guide/zodb.tex
+
+clobber:
+	rm -rf storage.pdf storage.ps storage/ zodb.pdf zodb.ps zodb/

trunk/doc/README.txt

+ZODB Documentation
+==================
+
+Simple text files
+-----------------
+
+This is a brief summary of the text documentation included with ZODB.
+Most of the text actually uses the restructured text format.  The
+summary lists the title and path of each document.
+
+BerkeleyDB Storages for ZODB
+Doc/BDBStorage.txt
+
+Using zdctl and zdrun to manage server processes
+Doc/zdctl.txt
+
+ZEO Client Cache
+Doc/ZEO/cache.txt
+
+Running a ZEO Server HOWTO
+Doc/ZEO/howto.txt
+
+ZEO Client Cache Tracing
+Doc/ZEO/trace.txt
+
+Formatted documents
+-------------------
+
+There are two documents written the Python documentation tools.
+
+  ZODB/ZEO Programming Guide
+    PDF:  zodb.pdf
+    HTML: zodb/zodb.html
+
+  ZODB Storage API
+    PDF:  storage.pdf
+    HTML: storage/storage.html
+
+The documents located here can be formatted using the mkhowto script
+which is part of the Python documentation tools.  The recommended use
+of this script is to create a symlink from some handy bin/ directory
+to the script, located in Doc/tools/mkhowto in the Python source
+distribution; that script will locate the various support files it
+needs appropriately.
+
+The Makefile contains the commands to produce both the PDF and HTML
+versions of the documents.

trunk/doc/storage.tex

+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% Copyright (c) 2001, 2002, 2003 Zope Corporation and Contributors.
+% All Rights Reserved.
+%
+% This software is subject to the provisions of the Zope Public License,
+% Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+% THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+% WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+% WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+% FOR A PARTICULAR PURPOSE.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\documentclass{howto}
+
+\title{ZODB Storage API}
+
+\release{1.00}
+
+\author{Zope Corporation}
+\authoraddress{
+    Lafayette Technology Center\\
+    513 Prince Edward Street\\
+    Fredericksburg, VA 22401\\
+    \url{http://www.zope.com/}
+}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+\noindent
+A ZODB storage provides the low-level storage for ZODB transactions.
+Examples include FileStorage, OracleStorage, and bsddb3Storage.  The
+storage API handles storing and retrieving individual objects in a
+transaction-specifc way.  It also handles operations like pack and
+undo.  This document describes the interface implemented by storages.
+\end{abstract}
+
+\tableofcontents
+
+
+\section{Concepts}
+
+\subsection{Versions}
+
+Versions provide support for long-running transactions.  They extend
+transaction semantics, such as atomicity and serializability, to
+computation that involves many basic transactions, spread over long
+periods of time, which may be minutes, or years.
+
+Versions were motivated by a common problem in website management,
+but may be useful in other domains as well.  Often, a website must be
+changed in such a way that changes, which may require many operations
+over a period of time, must not be visible until completed and
+approved.  Typically this problem is solved through the use of
+\dfn{staging servers}.  Essentially, two copies of a website are
+maintained.  Work is performed on a staging server.  When work is
+completed, the entire site is copied from the staging server to the
+production server.  This process is too resource intensive and too
+monolithic.  It is not uncommon for separate unrelated changes to be
+made to a website and these changes will need to be copied to the
+production server independently.  This requires an unreasonable amount
+of coordination, or multiple staging servers.
+
+ZODB addresses this problem through long-running transactions, called
+\dfn{versions}.  Changes made to a website can be made to a version
+(of the website).  The author sees the version of the site that
+reflects the changes, but people working outside of the version cannot
+see the changes.  When the changes are completed and approved, they
+can be saved, making them visible to others, almost instantaneously.
+
+Versions require support from storage managers. Version support is an
+optional feature of storage managers and support in a particular
+database will depend on support in the underlying storage manager.
+
+
+\section{Storage Interface}
+
+General issues:
+
+The objects are stored as Python pickles.  The pickle format is
+important, because various parts of ZODB depend on it, e.g. pack.
+
+Conflict resolution
+
+Various versions of the interface.
+
+Concurrency and transactions.
+
+The various exceptions that can be raised.
+
+An object that implements the \class{Storage} interface must support
+the following methods:
+
+\begin{methoddesc}{tpc_begin}{transaction\optional{, tid\optional{,
+        status}}}
+  Begin the two-phase commit for \var{transaction}.  
+
+  This method blocks until the storage is in the not committing state,
+  and then places the storage in the committing state. If the storage
+  is in the committing state and the given transaction is the
+  transaction that is already being committed, then the call does not
+  block and returns immediately without any effect.
+
+  The optional \var{tid} argument specifies the timestamp to be used
+  for the transaction ID and the new object serial numbers.  If it is
+  not specified, the implementation chooses the timestamp.
+
+  The optional \var{status} argument, which has a default value of
+  \code{'~'}, has something to do with copying transactions.
+\end{methoddesc}
+
+\begin{methoddesc}{store}{oid, serial, data, version, transaction}
+  Store \var{data}, a Python pickle, for the object ID identified by
+  \var{oid}.  A Storage need not and often will not write data
+  immediately.  If data are written, then the storage should be
+  prepared to undo the write if a transaction is aborted.
+  
+  The value of \var{serial} is opaque; it should be the value returned
+  by the \method{load()} call that read the object.  \var{version} is
+  a string that identifies the version or the empty string.
+  \var{transaction}, an instance of
+  \class{ZODB.Transaction.Transaction}, is the current transaction.
+  The current transaction is the transaction passed to the most recent
+  \method{tpc_begin()} call.
+    
+  There are several possible return values, depending in part on
+  whether the storage writes the data immediately.  The return value
+  will be one of:
+
+  \begin{itemize}
+        \item \code{None}, indicating the data has not been stored yet
+        \item a string, containing the new serial number for the
+          object
+        \item a sequence of object ID, serial number pairs, containing the
+          new serial numbers for objects updated by earlier
+          \method{store()} calls that are part of this transaction.
+          If the serial number is not a string, it is an exception
+          object that should be raised by the caller.
+          \note{This explanation is confusing; how to tell the
+          sequence of pairs from the exception?  Barry, Jeremy, please
+          clarify here.}
+  \end{itemize}
+    
+  Several different exceptions can be raised when an error occurs.
+
+  \begin{itemize}
+        \item \exception{ConflictError} is raised when \var{serial}
+          does not match the most recent serial number for object
+          \var{oid}. 
+
+        \item \exception{VersionLockError} is raised when object
+          \var{oid} is locked in a version and the \var{version}
+          argument contains a different version name or is empty.
+
+        \item \exception{StorageTransactionError} is raised when
+          \var{transaction} does not match the current transaction.
+   
+        \item \exception{StorageError} or, more often, a subclass of
+          it, is raised when an internal error occurs while the
+          storage is handling the \method{store()} call.
+  \end{itemize}
+\end{methoddesc}
+
+\begin{methoddesc}{restore}{oid, serial, data, version, transaction}
+  A lot like \method{store()} but without all the consistency checks.
+  This should only be used when we \emph{know} the data is good, hence
+  the method name.  While the signature looks like \method{store()},
+  there are some differences:
+
+  \begin{itemize}
+        \item \var{serial} is the serial number of this revision, not
+          of the previous revision.  It is used instead of
+          \code{self._serial}, which is ignored.
+
+        \item Nothing is returned.
+
+        \item \var{data} can be \code{None}, which indicates a George
+          Bailey object (one who's creation has been transactionally
+          undone).
+  \end{itemize}
+\end{methoddesc}
+
+\begin{methoddesc}{new_oid}{}
+  XXX
+\end{methoddesc}
+
+\begin{methoddesc}{tpc_vote}{transaction}
+  XXX
+\end{methoddesc}
+
+\begin{methoddesc}{tpc_finish}{transaction, func}
+  Finish the transaction, making any transaction changes
+  permanent.  Changes must be made permanent at this point.
+
+  If \var{transaction} is not the current transaction, nothing
+  happens.
+  
+  \var{func} is called with no arguments while the storage lock is
+  held, but possibly before the updated date is made durable.  This
+  argument exists to support the \class{Connection} object's
+  invalidation protocol.
+\end{methoddesc}
+
+\begin{methoddesc}{abortVersion}{version, transaction}
+  Clear any changes made by the given version.  \var{version} is the
+  version to be aborted; it may not be the empty string.
+  \var{transaction} is the current transaction.
+
+  This method is state dependent. It is an error to call this method
+  if the storage is not committing, or if the given transaction is not
+  the transaction given in the most recent \method{tpc_begin()}.
+
+  If undo is not supported, then version data may be simply
+  discarded.  If undo is supported, however, then the
+  \method{abortVersion()} operation must be undoable, which implies
+  that version data must be retained.  Use the \method{supportsUndo()}
+  method to determine if the storage supports the undo operation.
+\end{methoddesc}
+
+\begin{methoddesc}{commitVersion}{source, destination, transaction}
+  Store changes made in the \var{source} version into the
+  \var{destination} version.  A \exception{VersionCommitError} is
+  raised if the \var{source} and \var{destination} are equal or if
+  \var{source} is an empty string.  The \var{destination} may be an
+  empty string, in which case the data are saved to non-version
+  storage.
+
+  This method is state dependent.  It is an error to call this method
+  if the storage is not committing, or if the given transaction is not
+  the transaction given in the most recent \method{tpc_begin()}.
+
+  If the storage doesn't support undo, then the old version data may
+  be discarded.  If undo is supported, then this operation must be
+  undoable and old transaction data may not be discarded.  Use the
+  \method{supportsUndo()} method to determine if the storage supports
+  the undo operation.
+\end{methoddesc}
+
+\begin{methoddesc}{close}{}
+  Finalize the storage, releasing any external resources.  The storage
+  should not be used after this method is called.
+\end{methoddesc}
+
+\begin{methoddesc}{lastSerial}{oid}
+  Returns the serial number for the last committed transaction for the
+  object identified by \var{oid}.  If there is no serial number for
+  \var{oid} --- which can only occur if it represents a new object ---
+  returns \code{None}.
+  \note{This is not defined for \class{ZODB.BaseStorage}.}
+\end{methoddesc}
+
+\begin{methoddesc}{lastTransaction}{}
+  Return transaction ID for last committed transaction.
+  \note{This is not defined for \class{ZODB.BaseStorage}.}
+\end{methoddesc}
+
+\begin{methoddesc}{getName}{}
+  Returns the name of the store.  The format and interpretation of
+  this name is storage dependent.  It could be a file name, a database
+  name, etc.
+\end{methoddesc}
+
+\begin{methoddesc}{getSize}{}
+  An approximate size of the database, in bytes.
+\end{methoddesc}
+
+\begin{methoddesc}{getSerial}{oid}
+  Return the serial number of the most recent version of the object
+  identified by \var{oid}.
+\end{methoddesc}
+
+\begin{methoddesc}{load}{oid, version}
+  Returns the pickle data and serial number for the object identified
+  by \var{oid} in the version \var{version}.
+\end{methoddesc}
+
+\begin{methoddesc}{loadSerial}{oid, serial}
+  Load a historical version of the object identified by \var{oid}
+  having serial number \var{serial}.
+\end{methoddesc}
+
+\begin{methoddesc}{modifiedInVersion}{oid}
+  Returns the version that the object with identifier \var{oid} was
+  modified in, or an empty string if the object was not modified in a
+  version.
+\end{methoddesc}
+
+\begin{methoddesc}{isReadOnly}{}
+  Returns true if the storage is read-only, otherwise returns false.
+\end{methoddesc}
+
+\begin{methoddesc}{supportsTransactionalUndo}{}
+  Returns true if the storage implementation supports transactional
+  undo, or false if it does not.
+  \note{This is not defined for \class{ZODB.BaseStorage}.}
+\end{methoddesc}
+
+\begin{methoddesc}{supportsUndo}{}
+  Returns true if the storage implementation supports undo, or false
+  if it does not.
+\end{methoddesc}
+
+\begin{methoddesc}{supportsVersions}{}
+  Returns true if the storage implementation supports versions, or
+  false if it does not.
+\end{methoddesc}
+
+\begin{methoddesc}{transactionalUndo}{transaction_id, transaction}
+  Undo a transaction specified by \var{transaction_id}.  This may need
+  to do conflict resolution.
+  \note{This is not defined for \class{ZODB.BaseStorage}.}
+\end{methoddesc}
+
+\begin{methoddesc}{undo}{transaction_id}
+   Undo the transaction corresponding to the transaction ID given by
+   \var{transaction_id}.  If the transaction cannot be undone, then
+   \exception{UndoError} is raised.  On success, returns a sequence of
+   object IDs that were affected.
+\end{methoddesc}
+
+\begin{methoddesc}{undoInfo}{XXX}
+  XXX
+\end{methoddesc}
+
+\begin{methoddesc}{undoLog}{\optional{first\optional{,
+                            last\optional{, filter}}}}
+  Returns a sequence of \class{TransactionDescription} objects for
+  undoable transactions.  \var{first} gives the index of the first
+  transaction to be retured, with \code{0} (the default) being the
+  most recent.
+
+  \note{\var{last} is confusing; can Barry or Jeremy try to explain
+  this?}
+
+  If \var{filter} is provided and not \code{None}, it must be a
+  function which accepts a \class{TransactionDescription} object as a
+  parameter and returns true if the entry should be reported.  If
+  omitted or \code{None}, all entries are reported.
+\end{methoddesc}
+
+\begin{methoddesc}{versionEmpty}{version}
+  Return true if there are no transactions for the specified version.
+\end{methoddesc}
+
+\begin{methoddesc}{versions}{\optional{max}}
+  Return a sequence of the versions stored in the storage.  If
+  \var{max} is given, the implementation may choose not to return more
+  than \var{max} version names.
+\end{methoddesc}
+
+\begin{methoddesc}{history}{oid\optional{, version\optional{,
+                            size\optional{, filter}}}}
+  Return a sequence of \class{HistoryEntry} objects.  The information
+  provides a log of the changes made to the object.  Data are reported
+  in reverse chronological order.  If \var{version} is given, history
+  information is given with respect to the specified version, or only
+  the non-versioned changes if the empty string is given.  By default,
+  all changes are reported.  The number of history entries reported is
+  constrained by \var{size}, which defaults to \code{1}.  If
+  \var{filter} is provided and not \code{None}, it must be a function
+  which accepts a \class{HistoryEntry} object as a parameter and
+  returns true if the entry should be reported.  If omitted or
+  \code{None}, all entries are reported.
+\end{methoddesc}
+
+\begin{methoddesc}{pack}{t, referencesf}
+  Remove transactions from the database that are no longer needed to
+  maintain the current state of the database contents.  Undo will not
+  be restore objects to states from before the most recent call to
+  \method{pack()}.
+\end{methoddesc}
+
+\begin{methoddesc}{copyTransactionsFrom}{other\optional{, verbose}}
+  Copy transactions from another storage, given by \var{other}.  This
+  is typically used when converting a database from one storage
+  implementation to another.  This will use \method{restore()} if
+  available, but will use \method{store()} if \method{restore()} is
+  not available.  When \method{store()} is needed, this may fail with
+  \exception{ConflictError} or \exception{VersionLockError}.
+\end{methoddesc}
+
+\begin{methoddesc}{iterator}{\optional{start\optional{, stop}}}
+  Return a iterable object which produces all the transactions from a
+  range.  If \var{start} is given and not \code{None}, transactions
+  which occurred before the identified transaction are ignored.  If
+  \var{stop} is given and not \code{None}, transactions which occurred
+  after the identified transaction are ignored; the specific
+  transaction identified by \var{stop} will be included in the series
+  of transactions produced by the iterator.
+  \note{This is not defined for \class{ZODB.BaseStorage}.}
+\end{methoddesc}
+
+\begin{methoddesc}{registerDB}{db, limit}
+  Register a database \var{db} for distributed storage invalidation
+  messages.  The maximum number of objects to invalidate is given by
+  \var{limit}.  If more objects need to be invalidated than this
+  limit, then all objects are invalidated.  This argument may be
+  \code{None}, in which case no limit is set.  Non-distributed
+  storages should treat this is a null operation.  Storages should
+  work correctly even if this method is not called.
+\end{methoddesc}
+
+
+\section{ZODB.BaseStorage Implementation}
+
+\section{Notes for Storage Implementors}
+
+
+\section{Distributed Storage Interface}
+
+Distributed storages support use with multiple application processes.
+
+Distributed storages have a storage instance per application and some
+sort of central storage server that manages data on behalf of the
+individual storage instances.
+
+When a process changes an object, the object must be invaidated in all
+other processes using the storage.  The central storage sends a
+notification message to the other storage instances, which, in turn,
+send invalidation messages to their respective databases.
+
+\end{document}

trunk/doc/zdctl.txt

+Using zdctl and zdrun to manage server processes
+================================================
+
+
+Summary
+-------
+
+Starting with Zope 2.7 and ZODB 3.2, Zope has a new way to configure
+and control server processes.  This file documents the new approach to
+server process management; the new approach to configuration is
+documented elsewhere, although some examples will be given here.  We
+use the ZEO server as a running example, although this isn't a
+complete manual for configuring or running ZEO.
+
+This documentation applies to Unix/Linux systems; zdctl and zdrun do
+not work on Windows.
+
+
+Prerequisites
+-------------
+
+This document assumes that you have installed the ZODB3 software
+(version 3.2 or higher) using a variation on the following command,
+given from the root directory of the ZODB3 distribution::
+
+  $ python setup.py install
+
+This installs the packages ZConfig, ZEO, zdaemon, zLOG, ZODB and
+various other needed packages and extension modules in the Python
+interpreter's site-packages directory, and installs scripts including
+zdctl.py, zdrun.py, runzeo.py and mkzeoinst.py in /usr/local/bin
+(actually the bin directory from which the python interpreter was
+loaded).
+
+When you receive ZODB as a part of Zope (version 2.7 or higher), the
+installation instructions will explain how to reach a similar state.
+
+
+Introduction
+------------
+
+The most basic way to run a ZEO server is using the following
+command::
+
+  $ runzeo.py -a 9999 -f Data.fs
+
+Here 9999 is the ZEO port (you can pick your own unused TCP port
+number in the range 1024 through 65535, inclusive); Data.fs is the
+storage file.  Again, you can pick any filename you want; the
+ZODB.FileStorage module code creates this file and various other files
+with additional extensions, like Data.fs.index, Data.fs.lock, and
+Data.fs.tmp.
+
+If something's wrong, for example if you picked a bad port number or
+filename, you'll get an error message or an exception right away and
+runzeo.py will exit with a non-zero exit status.  The exit status is 2
+for command line syntax errors, 1 for other errors.
+
+If all's well, runzeo.py will emit a few logging messages to stderr
+and start serving, until you hit ^C.  For example::
+
+  $ runzeo.py -a 9999 -f Data.fs
+  ------
+  2003-01-24T11:49:27 INFO(0) RUNSVR opening storage '1' using FileStorage
+  ------
+  2003-01-24T11:49:27 INFO(0) ZSS:23531 StorageServer created RW with
+  storages: 1:RW:Data.fs
+  ------
+  2003-01-24T11:49:27 INFO(0) zrpc:23531 listening on ('', 9999)
+
+At this point you can hit ^C to stop it; runzeo.py will catch the
+interrupt signal, emit a few more log messages and exit::
+
+  ^C
+  ------
+  2003-01-24T12:11:15 INFO(0) RUNSVR terminated by SIGINT
+  ------
+  2003-01-24T12:11:15 INFO(0) RUNSVR closing storage '1'
+  $ 
+
+This may be fine for testing, but a bad idea for running a ZEO server
+in a production environment.  In production, you want the ZEO server
+to be run as a daemon process, you want the log output to go to a
+file, you want the ZEO server to be started when the system is
+rebooted, and (usually) you want the ZEO server to be automatically
+restarted when it crashes.  You should also have a log rotation policy
+in place so that your disk doesn't fill up with log messages.
+
+The zdctl/zdrun combo can take care of running a server as a daemon
+process and restarting it when it crashes.  It can also be used to
+start it when the system is rebooted.  Sending log output to a file is
+done by adjusting the ZEO server configuration.  There are many fine
+existing tools to rotate log files, so we don't provide this
+functionality; zdctl has a command to send the server process a
+SIGUSR2 signal to tell it to reopen its log file after log rotation
+has taken place (the ZEO server has a signal handler that catches
+SIGUSR2 for this purpose).
+
+In addition, zdctl lets a system administrator or developer control
+the server process.  This is useful to deal with typical problems like
+restarting a hanging server or adjusting a server's configuration.
+
+The zdctl program can be used in two ways: in one-shot mode it
+executes a single command (such as "start", "stop" or "restart"); in
+interactive mode it acts much like a typical Unix shell or the Python
+interpreter, printing a prompt to standard output and reading commands
+from standard input.  It currently cannot be used to read commands
+from a file; if you need to script it, you can use a shell script
+containing repeated one-shot invocations.
+
+zdctl can be configured using command line options or a configuration
+file.  In practice, you'll want to use a configuration file; but first
+we'll show some examples using command line options only.  Here's a
+one-shot zdctl command to start the ZEO server::
+
+  $ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" start
+
+The -p option specifies the server program; it is the runzeo
+invocation that we showed before.  The start argument tells it to
+start the process.  What actually happens is that zdctl starts zdrun,
+and zdrun now manages the ZEO server process.  The zdctl process exits
+once zdrun has started the ZEO server process; the zdrun process stays
+around, and when the ZEO server process crashes it will restart it.
+
+To check that the ZEO server is now running, use the zdctl status
+command::
+
+  $ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" status
+
+This prints a one-line message telling you that the program is
+running.  To stop the ZEO server, use the zdctl stop command::
+
+  $ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" stop
+
+To check that is no longer running, use the zdctl status command
+again.
+
+
+Daemon mode
+-----------
+
+If you are playing along on your computer, you cannot have missed that
+some log output has been spewing to your terminal window.  While this
+may give you a warm and fuzzy feeling that something is actually
+happening, after a whiile it can get quite annoying (especially if
+clients are actually connecting to the server).  This can be avoided
+by using the -d flag, which enables "daemon mode"::
+
+  $ zdctl.py -d -p "runzeo.py -a 9999 -f Data.fs" start
+
+Daemon mode does several subtle things; see for example section 13.3
+of "Advanced Programming in the UNIX Environment" by Richard Stevens
+for a good explanation of daemon mode.  For now, the most important
+effect is that the standard input, output and error streams are
+redirected to /dev/null, and that the process is "detached" from your
+controlling tty, which implies that it won't receive a SIGHUP signal
+when you log out.
+
+
+Using a configuration file
+--------------------------
+
+I hope you are using a Unix shell with command line history, otherwise
+entering the examples above would have been quite a pain.  But a
+better way to control zdctl and zdrun's many options without having to
+type them over and over again is to use a configuration file.  Here's
+a small configuration file; place this in the file "zeoctl.conf" (the
+name is just a convention; you can call it "foo" if you prefer)::
+
+  # Sample zdctl/zdrun configuration
+  <runner>
+    program       runzeo.py -a 9999 -f Data.fs
+    daemon	  true
+    directory     /tmp/zeohome
+    socket-name   /tmp/zeohome/zdsock
+  </runner>
+
+The "program" and "daemon" lines correspond to the -p and -d command
+line options discussed above.  The "directory" line is new.  It
+specifies a directory into which zdrun (but not zdctl!) chdirs.  This
+directory should exist; zdctl won't create it for you.  The Data.fs
+filename passed to runzeo.py is interpreted relative to this
+directory.  Finally, the "socket-name" line names the Unix domain
+socket that is used for communication between zdctl and zdrun.  It
+defaults to zdsock in the current directory, a default you definitely
+want to override for production usage.
+
+To invoke zdctl with a configuration file, use its -C option to name
+the configuration file, for example::
+
+  $ zdctl.py -C zeoctl.conf start
+
+  $ zdctl.py -C zeoctl.conf status
+
+  $ zdctl.py -C zeoctl.conf stop
+
+
+Interactive mode
+----------------
+
+Using a configuration file makes it a little easier to repeatedly
+start, stop and request status of a particular server, but it still
+requires typing the configuration file name on each command.
+Fortunately, zdctl.py can be used as an interactive "shell" which lets
+you execute repeated commands for the same server.  Simply invoke
+zdctl.py without the final argument ("start", "status" or "stop" in
+the above examples)::
+
+  $ zdctl.py -C zeoctl.conf
+  program: runzeo.py -a 9999 -f Data.fs
+  daemon manager not running
+  zdctl> 
+
+The first two lines of output are status messages (and could be
+different in your case); the final line is the interactive command
+prompt.  At this prompt, you can type commands::
+
+  zdctl> help
+
+  Documented commands (type help <topic>):
+  ========================================
+  EOF             fg              foreground      help            kill
+  logreopen       logtail         quit            reload          restart
+  shell           show            start           status          stop
+  wait            
+
+  zdctl> help start
+  start -- Start the daemon process.
+	   If it is already running, do nothing.
+  zdctl> start
+  daemon process started, pid=31580
+  zdctl> status
+  program running; pid=31580
+  zdctl> stop
+  daemon process stopped
+  zdctl> quit
+  daemon manager not running
+  $ 
+
+In short, the commands you can type at the interactive prompt are the
+same commands (with optional arguments) that you can use as positional
+arguments on the zdctl.py command line.
+
+The interactive shell has some additional features:
+
+- Line editing and command line history using the standard GNU
+  readline module.
+
+- A blank line repeats the last command (especially useful for status).
+
+- Command and argument completion using the TAB key.
+
+One final note: some people don't like it that an invocation without
+arguments enters interactive mode.  If this describes you, there's an
+easy way to disable this feature: add a line saying
+
+  default-to-interactive false
+
+to the zeoctl.conf file.  You can still enter interactive mode by
+using the -i option.
+
+
+Using mkzeoinst.py
+------------------
+
+If you still think that all of the above is a lot of typing, you're
+right.  Fortunately, there's a simple utility that help you creating
+and configuring a ZEO server instance.  mkzeoinst.py requires one
+argument, the ZEO server's "home directory".  After that, you can
+optionally specify a service port number; the port defaults to 9999.
+
+mkzeoinst.py creates the server home directory (and its ancestor
+directories if necessary), and then creates the following directory
+substructure:
+
+  bin/ - directory for scripts (zeoctl)
+  etc/ - directory for configuration files (zeo.conf, zeoctl.conf)
+  log/ - directory for log files (zeo.log, zeoctl.log)
+  var/ - directory for data files (Data.fs and friends)
+
+If the server home directory or any of its subdirectories already
+exist, mkzeoinst.py will note this and assume you are rebuilding an
+existing instance.  (In fact, it prints a message for each directory
+it creates but is silent about existing directories.)
+
+It then creates the following files:
+
+  bin/zeoctl      - executable shell script to run zdctl.py
+  etc/zeo.conf    - configuration file for ZEO
+  etc/zeoctl.conf - configuration file for zdrun.py and zdctl.py
+
+If any of the files it wants to create already exists and is
+non-empty, it does not write the file.  (An empty file will be
+overwritten though.)  If the existing contents differ from what it
+would have written if the file didn't exist, it prints a warning
+message; otherwise the skipping is silent.
+
+Other errors (e.g. permission errors creating or reading files or
+directories) cause mkzeoinst.py to bail with an error message; it does
+not clean up the work already done.
+
+The created files contain absolute path references to all of the
+programs, files, directories used.  They also contain default values
+for most configuration settings that one might normally want to
+configure.  Most configured settings are the same as the defaults;
+however, daemon mode is on while the regular default is off.  Log
+files are configured to go into the log directory.  If configures
+separate log files for zdrun.py/zdctl.py (log/zeoctl.log) and for the
+ZEO server itself (log/zeo.log).  Once created, the files are yours;
+feel free to edit them to suit your taste.
+
+The bin/zeoctl script should be invoked with the positional arguments
+(e,g, "start", "stop" or "status") that you would pass to zdctl.py;
+the script hardcodes the configuration file so you don't have to pass
+that.  It can also be invoked without arguments to enter interactive
+mode.
+
+One final detail: if you want the ZEO server to be started
+automatically when the machine is rebooted, and you're lucky enough to
+be using a recent Red Hat (or similar) system, you can copy the
+bin/zeoctl script into the /etc/rc.d/init.d/ directory and use
+chkconfig(8) to create the correct symlinks to it; the bin/zeoctl
+script already has the appropriate magical comments for chkconfig.
+
+
+zdctl reference
+---------------
+
+XXX TBD
+
+
+zdrun reference
+---------------
+
+XXX TBD