# HG changeset patch
# User Ralph Meijer <ralphm@ik.nu>
# Date 1212141864 0
# Node ID 8ab16e319bb812e1681a7668f553d98273780fd0
# Parent  a219fe70a762aded99a8e2f35add8939c7580f88
Release Idavoll 0.7.3.

diff -r a219fe70a762 -r 8ab16e319bb8 INSTALL
--- a/INSTALL	Fri May 30 09:56:08 2008 +0000
+++ b/INSTALL	Fri May 30 10:04:24 2008 +0000
@@ -1,41 +1,124 @@
 Requirements
 ============
 
-- Twisted >= 8.0.1
+- Twisted >= 8.0.1:
+   - Twisted Core
+   - Twisted Conch (for idavoll-http)
+   - Twisted Web (for idavoll-http)
+   - Twisted Web2 (for idavoll-http)
+   - Twisted Words
 - uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid)
-- A Jabber server that supports the component protocol (JEP-0114)
 - Wokkel >= 0.3.1 (http://wokkel.ik.nu/)
+- simplejson (for idavoll-http)
+- A Jabber server that supports the component protocol (XEP-0114)
 
 For the PostgreSQL backend, the following is also required:
 
 - PostgreSQL
 - pyPgSQL
 
+
 Installation
 ============
 
-Run:
+Idavoll uses setuptools for package building and installing, and is also
+available through the Python Package Index (pypi). The easiest way to
+install idavoll is:
+
+  easy_install idavoll
+
+This will pull down the dependencies, if needed, except for the Twisted
+packages.
+
+To building from source run:
+
+  python setup.py build
+
+Then, to install run the following, possibly as root:
 
   python setup.py install
 
+See the setuptools documentation for further information on changing
+installation locations.
+
+
 Configuration
 =============
 
-The configuration file is created using Twisted's mktap, which needs a number
-of parameters:
+Idavoll uses Twisted's twistd command for running its services. Starting with
+Twisted 2.5.0, twistd supports running Twisted Application Plugins directly,
+without the use of mktap. In Twisted 8.1.0, the use of mktap for configuration
+is deprecated. These instructions will not cover the use of mktap anymore, but
+you can use TAC files to store a configuration, as described near the end
+of this document.
+
+Idavoll provides two types of storage for the backend: a memory-based storage
+facility, which is volatile, and a persistent storage facility using
+PostgreSQL. By default, the memory backend is used.
+
+For using the PostgreSQL backend, create a database (for example named pubsub)
+like so:
+
+  createdb pubsub
+  psql pubsub <db/pubsub.sql
+
+To use this backend, add the --backend=pgsql parameter to twistd, along
+with the optional connection parameters (see twistd idavoll --help).
+
+Your Jabber server must also be configured to accept component connections,
+see below for details.
+
+
+Running Idavoll
+===============
+
+Idavoll provides two twistd plugins: idavoll and idavoll-http. The former
+provides a generic publish-subscribe service, and the latter adds to that an
+HTTP interface to access some of the features of the Idavoll backend, and also
+provides a way to subscribe to, and receive notifications from, remote
+publish-subscribe nodes.
+
+The minimal example for running idavoll is:
+
+  twistd idavoll
+
+This will start the service and run it in the background. It generates a
+file twistd.pid that holds the PID of the service and a log file twistd.log.
+The twistd utility has a fair number of options that might be useful, and
+can be viewed with:
+
+  twistd --help
+
+When the service starts, it will connect to the Jabber server at the local
+machine using the component protocol, and assumes the JID 'pubsub'. This
+assumes a couple of defaults which can be overridden by passing parameters to
+the twistd plugin. You can get an overview of the parameters and their defaults
+using:
+
+  twistd idavoll --help
+
+In particular, the following parameters will be of interest:
 
  --jid: The Jabber ID the component will assume.
  --rport: the port number of the Jabber server to connect to
  --secret: the secret used to authenticate with the Jabber server.
  --backend: the backend storage facility to be used (memory or PostgreSQL).
 
-The default settings of mktap for Idavoll use the memory database and assume
-the default settings of jabberd 2.x for --rport and --secret.
+The defaults for Idavoll use the memory database and assume the default
+settings of jabberd 2.x for --rport and --secret.
+
+You may also want to provide the --verbose flag to see the traffic flow,
+for example to debug the configuration. Below some specifics for the
+different Jabber server implementations.
+
 
 jabberd 2.x
 ===========
+
 You can use the 'legacy' component support that defaults to port 5347 with
-secret 'secret'. You do not need to add anything specific for this service.
+secret 'secret'. These are the defaults of Idavoll, so you don't need to
+alter the connection details with a default jabberd 2.x install.
+
 
 jabberd 1.4.x
 =============
@@ -57,36 +140,18 @@
 how to interact with server side components using the protocol defined in
 JEP-0114.
 
-Then, in the same directory as this file run:
+Then, you can start Idavoll with:
 
-  mktap idavoll --rport=5347 --jid=pubsub.localhost --secret=secret
+  twistd idavoll --rport=5347 --jid=pubsub.localhost --secret=secret
 
 This uses the (default) memory based backend.
 
-For using the PostgreSQL backend, create a database (for example named pubsub)
-like so:
 
-  createdb pubsub
-  psql pubsub <db/pubsub.sql
-
-To use this backend, add the --backend=pgsql parameter to mktap.
-
-For viewing all options, run:
-
-  mktap idavoll --help
-
-The generated file idavoll.tap now holds the configuration.
+Using TAC files to store a configuration
+========================================
 
-Running
-=======
-
-Using the configuration file idavoll.tap, run:
-
-  twistd -of idavoll.tap
+Apart from the provided TAPs that can be run with twistd, you can also create
+a configuration file that can be used by twistd to start up Idavoll. You can
+find an example in doc/examples/idavoll.tac, which can be run using:
 
-This will start the service and run it in the background. It generates a
-file twistd.pid that holds the PID of the service and a log file twistd.log.
-The twistd utility has a fair number of options that might be useful, and
-can be viewed with:
-
-  twistd --help
+  twisted -y idavoll.tac 
diff -r a219fe70a762 -r 8ab16e319bb8 NEWS
--- a/NEWS	Fri May 30 09:56:08 2008 +0000
+++ b/NEWS	Fri May 30 10:04:24 2008 +0000
@@ -1,7 +1,10 @@
-x.x.x (yyyy-mm-dd)
+0.7.3 (2008-05-30)
 ==================
 
  - Return appropriate HTTP status codes on failed un-/subscription.
+ - Use ServiceMaker to setup twistd plugins, available as of Twisted 8.1.0.
+ - Require simplejson through setup.py.
+ - Update installation and configuration documentation in INSTALL.
 
 
 0.7.2 (2008-05-16)
diff -r a219fe70a762 -r 8ab16e319bb8 README
--- a/README	Fri May 30 09:56:08 2008 +0000
+++ b/README	Fri May 30 10:04:24 2008 +0000
@@ -1,4 +1,4 @@
-Idavoll 0.7.2
+Idavoll 0.7.3
 
 What is this?
 ================
diff -r a219fe70a762 -r 8ab16e319bb8 idavoll/tap.py
--- a/idavoll/tap.py	Fri May 30 09:56:08 2008 +0000
+++ b/idavoll/tap.py	Fri May 30 10:04:24 2008 +0000
@@ -12,7 +12,7 @@
 
 from idavoll.backend import BackendService
 
-__version__ = '0.7.2'
+__version__ = '0.7.3'
 
 class Options(usage.Options):
     optParameters = [
diff -r a219fe70a762 -r 8ab16e319bb8 setup.py
--- a/setup.py	Fri May 30 09:56:08 2008 +0000
+++ b/setup.py	Fri May 30 10:04:24 2008 +0000
@@ -6,13 +6,16 @@
 import sys
 from setuptools import setup
 
-install_requires = ['wokkel >= 0.3.1']
+install_requires = [
+    'wokkel >= 0.3.1',
+    'simplejson',
+]
 
 if sys.version_info < (2, 5):
     install_requires.append('uuid')
 
 setup(name='idavoll',
-      version='0.7.2',
+      version='0.7.3',
       description='Jabber Publish-Subscribe Service Component',
       author='Ralph Meijer',
       author_email='ralphm@ik.nu',