Some documentation updates and spelling fixes

README

@@ -46,12 +46,15 @@ Requirements
 
 - For python 2.4: ctypes http://python.net/crew/theller/ctypes/
   (packaged with later python versions)
+
   Note that setup.py does not define any dependency to 'ctypes' so you will
   have to install it explicitely.
 
-- MySQLdb http://sourceforge.net/projects/mysql-python
+- For storage nodes:
+
+  - MySQLdb: http://sourceforge.net/projects/mysql-python
 
-- ZODB 3.10 or later (requires python 2.5 or later, only for client nodes)
+- For client nodes: ZODB 3.10.x but it should work with ZODB >= 3.4
 
 Installation
 ============
@@ -74,12 +77,12 @@ d. Tell the cluster it can provide service::
 How to use
 ==========
 
+First make sure Python can import 'neo.client' package.
+
 In zope
 -------
 
-a. Copy neo directory to /path/to/your/zope/lib/python
-
-b. Edit your zope.conf, add a neo import and edit the `zodb_db` section by
+a. Edit your zope.conf, add a neo import and edit the `zodb_db` section by
    replacing its filestorage subsection by a NEOStorage one.
    It should look like::
 
@@ -93,23 +96,31 @@ b. Edit your zope.conf, add a neo import and edit the `zodb_db` section by
         mount-point /
     </zodb_db>
 
-c. Start zope
+b. Start zope
 
 In a Python script
 ------------------
 
-a. Set your PYTHONPATH in order to be able to import Zope lib::
-
-    $ export PYTHONPATH=/path/to/your/zope/lib/python:$PYTHONPATH
-
-b. Just create the storage object and play with it::
+Just create the storage object and play with it::
 
   from neo.client.Storage import Storage
   s = Storage(master_nodes="127.0.0.1:10010", name="main")
   ...
 
-  "name" and "master_nodes" parameters have the same meaning as in
-  configuration file.
+"name" and "master_nodes" parameters have the same meaning as in
+configuration file.
+
+Shutting down
+-------------
+
+There no administration command yet to stop properly a running cluster.
+So following manual actions should be done:
+
+a. Make sure all clients like Zope instances are stopped, so that cluster
+   become idle.
+b. Stop all master nodes first with a SIGINT or SIGTERM, so that storage nodes
+   don't become in OUT_OF_DATE state.
+c. At last stop remaining nodes with a SIGINT or SIGTERM.
 
 Deployment
 ==========

TODO

@@ -69,7 +69,7 @@ RC  - Review output of pylint (CODE)
       many places.
     - Clarify handler methods to call when a connection is accepted from a
       listening conenction and when remote node is identified
-      (cf. neo/bootstrap.py).
+      (cf. neo/lib/bootstrap.py).
     - Choose how to handle a storage integrity verification when it comes back.
       Do the replication process, the verification stage, with or without
       unfinished transactions, cells have to set as outdated, if yes, should the
@@ -77,7 +77,7 @@ RC  - Review output of pylint (CODE)
     - Implement proper shutdown (ClusterStates.STOPPING)
     - Review PENDING/HIDDEN/SHUTDOWN states, don't use notifyNodeInformation()
       to do a state-switch, use a exception-based mechanism ? (CODE)
-    - Split protocol.py in a 'protocol' module
+    - Split protocol.py in a 'protocol' module ?
     - Review handler split (CODE)
       The current handler split is the result of small incremental changes. A
       global review is required to make them square.
@@ -98,7 +98,7 @@ RC  - Review output of pylint (CODE)
       committed by future transactions.
 
     Storage
-    - Use Kyoto Cabinet instead of a stand-alone MySQL server.
+    - Use HailDB instead of a stand-alone MySQL server.
     - Notify master when storage becomes available for clients (LATENCY)
       Currently, storage presence is broadcasted to client nodes too early, as
       the storage node would refuse them until it has only up-to-date data (not
@@ -163,7 +163,7 @@ RC  - Review output of pylint (CODE)
     - Master node data redundancy (HIGH AVAILABILITY)
       Secondary master nodes should replicate primary master data (ie, primary
       master should inform them of such changes).
-      This data takes too long to extract from storage nodes, and loosing it
+      This data takes too long to extract from storage nodes, and losing it
       increases the risk of starting from underestimated values.
       This risk is (currently) unavoidable when all nodes stop running, but this
       case must be avoided.
@@ -223,8 +223,6 @@ RC  - Review output of pylint (CODE)
       distributed lock mechanisms, ...)
     - Choose how to compute the storage size
     - Make storage check if the OID match with it's partitions during a store
-    - Consider using out-of-band TCP feature.
-    - IPv6 support (address field, bind, name resolution)
     - Investigate delta compression for stored data
       Idea would be to have a few most recent revisions being stored fully, and
       older revision delta-compressed, in order to save space.

neo/master/transactions.py

@@ -191,7 +191,7 @@ class Transaction(object):
             for it.
             Does nothing if the node was not part of the transaction.
         """
-        # XXX: We might loose information that a storage successfully locked
+        # XXX: We might lose information that a storage successfully locked
         # data but was later found to be disconnected. This loss has no impact
         # on current code, but it might be disturbing to reader or future code.
         if self._prepared:

setup.py

+"""Distributed, redundant and transactional storage for ZODB
+"""
+
 from setuptools import setup, find_packages
 import os
 
@@ -34,12 +37,14 @@ extras_require['tests'] = ['zope.testing', 'psutil',
 setup(
     name = 'neoppod',
     version = '1.0a1',
-    description = 'Distributed, redundant and transactional storage for ZODB',
+    description = __doc__.strip(),
     author = 'NEOPPOD',
     author_email = 'neo-dev@erp5.org',
     url = 'http://www.neoppod.org/',
     license = 'GPL 2+',
+    platforms = ["any"],
     classifiers=classifiers.splitlines(),
+    long_description = ".. contents::\n\n" + open('README').read(),
     packages = find_packages(),
     py_modules = ['mock'],
     entry_points = {