Merge lp:~gingerchris/endroid/docs into lp:endroid

[ChrisD]

Merge in updated docs.

New wiki docs and a few other minor changes.

[Martin Morrison (isoschiz)]

review: Approve

=== renamed file 'src/README' => 'README'
--- src/README	2012-08-06 12:41:14 +0000
+++ README	2013-08-14 10:10:05 +0000
@@ -15,23 +15,4 @@
 ** You should register a Jabber ID for your EnDroid, e.g. at https://register.jabber.org/
 ** Put config in ~/.endroid/endroid.conf e.g.
 
-Example ~/.endroid/endroid.conf follows:
-============================================================
-[Setup]
-jid=[e-mail]
-secret=PASSWORD
-nick=MyEnDroid
-
-plugins=endroid.plugins.command,endroid.plugins.help,endroid.plugins.patternmatcher,endroid.plugins.speak,endroid.plugins.unhandled,endroid.plugins.whosonline,endroid.plugins.memo
-
-users=[e-mail]
-rooms=[e-mail]
-
-[Database]
-dbfile=/tmp/endroid.db
-
-[UserGroup:*]
-
-[Room:*]
-
-============================================================
+See etc/endroid.conf for an example config file.

=== modified file 'debian/endroid.install'
--- debian/endroid.install	2013-08-13 11:45:37 +0000
+++ debian/endroid.install	2013-08-14 10:10:05 +0000
@@ -1,4 +1,5 @@
 etc/endroid.conf etc/endroid/
+etc/endroid.conf usr/share/doc/endroid/examples/
 etc/init/endroid.conf etc/init/
 bin/endroid usr/bin/
 bin/endroid_echo usr/bin/

=== removed file 'doc/Installation'
--- doc/Installation	2012-08-27 23:19:45 +0000
+++ doc/Installation	1970-01-01 00:00:00 +0000
@@ -1,16 +0,0 @@
-#acl EnsoftLander:read,write,delete,admin,revert All:read
-
-= Installation =
-
-Installing EnDroid is straightforward. Installation packages are provided (currently only for Ubuntu) [[https://launchpad.net/endroid/+download|on Launchpad]]. It is also possible to run it directly by checking out the code:
-
- * `bzr branch lp:endroid` - to get the latest code. 
- * Create yourself a configuration file; an example is provided in the source in `etc/endroid.conf`
-  * You'll need an XMPP account to use for the bot
-  * '''Note''': EnDroid will "unfriend" any contact not directly configured. You have been warned!
- * cd into the `src` directory and run the `endroid.sh` script there, passing your configuration file path as an argument
-  * By default, EnDroid looks in `~/.endroid/endroid.conf`, then `/etc/endroid/endroid.conf`
-  * on platforms without `/bin/sh`, `python -m endroid` (or, for Python 2.6 and earlier, the slightly long-winded `python -c 'import endroid; endroid.main()'` can be used instead
-
-Note that EnDroid requires python 2.6 or later to run, and depends on Twisted, Wokkel, PyTZ and python-dateutil. 
-

=== renamed file 'src/endroid.graphml' => 'doc/module-diagram.graphml'
=== added directory 'doc/wiki'
=== renamed file 'doc/Configuration' => 'doc/wiki/Configuration'
--- doc/Configuration	2012-08-27 23:19:45 +0000
+++ doc/wiki/Configuration	2013-08-14 10:10:05 +0000
@@ -1,39 +1,69 @@
 #acl EnsoftLander:read,write,delete,revert,admin All:read
 
-= Configuration =
-
-The config file is formatted as a standard "ini" config file (using Python's standard !ConfigParser library). The sections/options are as follows (bold = required):
+<<TableOfContents>>
 
 == Basic Configuration ==
 
- * '''[Setup]'''
-  * '''jid''' - the JID from which to sign in, including a resource (`[e-mail]/resource`)
-  * '''secret''' - the password for this JID
-  * nick - the default nick to use in rooms. If this is not provided then it defaults to the JID.
-  * plugins - comma-or-newline-separated default list of plugins to use. If this is not provided then it defaults to none. (example plugin: endroid.plugins.echobot)
-   * Without plugins, your EnDroid isn't going to do much. Several features that might be expected to be core are actually implemented as plugins, so you should consider at a minimum running help, unhandled, command, patternmatcher
-  * users - list of users to allow. EnDroid will add all of these to its contacts, and will unfriend anyone who it sees who is not in this list.
-  * rooms - list of rooms to join. EnDroid will only join rooms in this list, regardless of whether they have configuration information further down the file.
-
- * [Database]
-  * dbfile - the location of the database file. In a default installation this will be at `/var/lib/endroid/db/endroid.db`
- * [!UserGroup:*]
-  * plugins - if this is specified, then it replaces the plugins directive in the Setup section for all single user chats. Otherwise, defaults to equal it.
- * [Room:*]
-  * plugins - ...same, but for all rooms.
-  * nick - if specified, overrides the nick directive from the Setup section, otherwise defaults to that.
- * [UserGroup:Group Name]
-  * users - list of all users' JIDs in the group.
-  * plugins - if this is specified, then it replaces the current default for users (i.e. that in !UserGroup:*, which equally could be taken from Setup...)
- * [Room:Room JID]
-  * plugins - if this is specified, then it replaces the current default for rooms (i.e. that in Room:*, which equally could be taken from Setup...)
-  * nick - you get the idea
- * [Plugin:Plugin Package]
-  * whatever options the plugin supports
-
-== Further Config ==
-
-If more detailed configuration is required, plugins can be configured on a per-room basis.
-
-In the same folder as the standard configuration file, the plugins can have a filename plugin-!PluginName.cfg file. Sections are [Room:RoomName], then the same directives go in here as under the [Plugin:...] sections.
+!EnDroid reads all of its config from a single configuration file, searched for at (in order):
+ * conffile as specified on the command file e.g. `endroid.sh <conffile>`.
+ * `ENDROID_CONF` environment variable.
+ * `~/.endroid/endroid.conf` (recommended)
+ * `/etc/endroid/endroid.conf`
+
+An example config file can be found at `/usr/share/doc/endroid/examples/endroid.conf` or at `etc/endroid.conf` in the source.
+The basic sections of the config file are described below:
+
+{{{#!python
+# Comments are denoted by a hash character in the first column
+
+[Setup]
+# EnDroid's jabber login details.
+jid = [e-mail]/planet
+password = secret
+
+# EnDroid's default nickname. If not specified, set to the part of jid before the @
+# nick = Marvin
+
+# EnDroid's full contact list. Users on this list will be added as friends,
+# users not on this list will be removed from contacts and will be unable
+# to communicate with EnDroid.
+users =
+
+# What rooms EnDroid will attempt to create and join. Defaults to []
+# rooms = [e-mail],
+
+# What usergroup EnDroid will register plugins with. Defaults to ['all']
+# groups = all, admins
+
+logfile = ~/.endroid/endroid.log
+
+[Database]
+dbfile = ~/.endroid/endroid.db
+
+# a section matching groups and rooms with any name
+[ group | room : *]
+plugins=
+#    endroid.plugins.<your_plugin>,
+#    endroid.plugins.<other plugin your plugin depends on>,
+#    ...
+}}}
+
+== Some Notes on Syntax ==
+
+ * !EnDroid will try to interpret values in the config file as Python objects, so `my_var = 1`.
+ * Bools will only be converted if they are `True` or `False` (i.e. capitalised).
+ * Lists are detected by commas or newlines:{{{#!python
+my_list = multiple, entries, present
+my_list2 = newlines
+    also
+    mean
+    lists
+}}}
+ * For a list with a single item, a comma must be present at the end of the list:{{{#!python
+expects_a_list1 = foo
+# Will result in a string foo not a list
+
+expects_a_list2 = foo,
+# Will result in a list of items with only one entry - foo
+}}}
 

=== added file 'doc/wiki/Debugging'
--- doc/wiki/Debugging	1970-01-01 00:00:00 +0000
+++ doc/wiki/Debugging	2013-08-14 10:10:05 +0000
@@ -0,0 +1,127 @@
+#acl EnsoftLander:read,write,delete,revert,admin All:read
+
+<<TableOfContents>>
+
+= Logs =
+
+!EnDroid currently logs to two places (this is a bug - !EnDroid currently uses `twisted.log` ''and'' `python.logging` to generate log messages - these should be combined!)
+
+== The Console ==
+
+ * This is where basic log output is displayed (generated from the `logging.[info|debug|...]` calls in the code).
+   * The verbosity of this log can be altered with the `-l <integer>` flag, integer defaults to `1`. Lower numbers result in more logging.
+   * If something strange happens to !EnDroid and nothing is shown here, consult the log file.
+
+== The Logfile ==
+
+ * The log file as specified in `endroid.conf` (defaults to `~/.endroid/endroid.log`):
+   * This is where `twisted` does all its logging.
+   * If a `Deferred` has thrown an Exception - the traceback will be in this file.
+   * If something is going wrong and there are still no apparent errors here, use the `-t` flag to start !EnDroid and look for `bad-request` or `error` in the xml.
+   * Any `print` statements in the code will have their output redirected here.
+ * The location of the log file may be specified with the `-L` or `--logfile` +  `<logfile>` flag.
+
+= Debugging =
+
+== Manhole ==
+
+Manhole provides a way of controlling !EnDroid via ssh. It gives the user a python console through which all of !EnDroid's internals may be accessed as it is running.
+
+To enable Manhole, pass the flag: `-m <user_name> <password> <port>` to !EnDroid on startup. Ssh access is then achieved with `ssh <user_name>@localhost -p <port>` and entering the password.
+
+Once inside Manhole, the user has access to the active instance of !EnDroid via `droid`. For example:
+ * `droid.usermanagement._pms` - will return the dictionary of `{<room/group name> : <pluginmanager instance>}`
+ * `droid.usermanagement._pms['all'].get('endroid.plugins.<your_plugin_name>')` will return the instance of `<your_plugin>` active in the `'all'` usergroup.
+
+A user may also define functions, import modules and generally lark around as they would in a regular python prompt. (It is almost certainly worth, for example, writing a short module with some helper
+functions to reduce the amount of typing required in Manhole).
+
+=== A Usage Example ===
+
+Start up !EnDroid with manhole enabled:
+{{{#!highlight python
+me@localhost:~/endroid/src$ bash endroid.sh -t -m <user>
+<password> <port>
+11:06:46 INFO     EnDroid starting up with conffile 
+/home/<me>/.endroid/endroid.conf
+11:06:46 INFO     Found JID: <my-endroid-jid>
+11:06:46 INFO     Found Secret: **********
+...
+11:06:46 INFO     Starting manhole
+...
+}}}
+
+And in a separate console:
+{{{#!highlight python
+me@localhost:~/endroid/src$ ssh <user>@localhost -p <port>
+admin@localhost's password: <password>
+>>> # I'm now in a python prompt
+>>> 1+1
+2
+>>> droid
+<endroid.Endroid object at 0xabd614c>
+>>> # I fancy sending myself a message
+>>> droid.messagehandler.send_chat("[e-mail]", "Hi me, 
+all is well in manhole-land!")
+>>> # I received the chat message.
+>>> logging.info("Hi console log!")
+>>> # console log: 11:04:28 INFO     Hi console log!
+>>> # Ctrl-D to exit
+Connection to localhost closed.
+me@localhost:~$
+}}}
+
+=== An Import Example ===
+
+A useful helper module for debugging plugins.
+
+{{{#!highlight python
+# src/my_helper.py
+
+def get_loaded(droid, room_group):
+    """
+    Return the _loaded dict of {plugin_name : PluginProxy object}
+    for room_group.
+
+    Note that a PluginProxy object is just a wrapper round a Plugin
+    object, and all of the plugin's attributes/functions may be accessed
+    through it.
+
+    """
+    return droid.usermanagement._pms[room_group]._loaded
+
+def get_instance(droid, room_group, plugin_name):
+    """Get the instance of 'plugin_name' active in 'room_group'.
+
+    'plugin_name' may be the full plugin_name e.g. 'endroid.plugins.chuck'
+    or just the last part e.g. 'chuck'
+
+    """
+    dct = get_loaded(droid, room_group)
+    if plugin_name in dct:
+        return dct[plugin_name]
+    else:
+        for key, item in dct.items():
+            if plugin_name == key.split('.')[-1]:
+                return item
+        fmt = "Plugin '{}' not active in '{}'"
+        raise KeyError(fmt.format(plugin_name, room_group))
+}}}
+
+Then checking to see if our plugin's config has been properly loaded from in Manhole is easy:
+
+{{{#!highlight python
+>>> import my_helper
+>>> my_helper.get_loaded(droid, 'all').keys()
+['endroid.plugins.unhandled', 'endroid.plugins.patternmatcher',
+ 'endroid.plugins.httpinterface', 'endroid.plugins.roomowner', 
+ 'endroid.plugins.chuck', 'endroid.plugins.command', 
+ 'endroid.plugins.passthebomb', 'endroid.plugins.invite', 
+ 'endroid.plugins.help', 'endroid.plugins.broadcast']
+>>> my_helper.get_instance(droid, 'all', 'chuck').vars
+{'my_list': ['list', 'with', 'numbers', 1, 2, 3], 
+ 'my_list2': ['newlines', 'also', 'mean', 'lists'], 
+ 'my_int': 123, 'my_string': 'this is a string'}
+>>>
+}}}
+

=== added file 'doc/wiki/GettingStarted'
--- doc/wiki/GettingStarted	1970-01-01 00:00:00 +0000
+++ doc/wiki/GettingStarted	2013-08-14 10:10:05 +0000
@@ -0,0 +1,40 @@
+#acl EnsoftLander:read,write,delete,revert,admin All:read
+
+<<TableOfContents>>
+
+= Installation =
+
+Installing EnDroid is straightforward. Installation packages are provided (currently only for Ubuntu) [[https://launchpad.net/endroid/+download|on Launchpad]]. It is also possible to run it directly
+by checking out the code using `bzr branch lp:endroid`.
+
+  Note: !EnDroid requires python 2.7 or later to run, and depends on Twisted, Wokkel, PyTZ and python-dateutil.
+
+In order to run EnDroid needs to load certain settings from its config file. An example one is installed at `/usr/share/doc/endroid/examples/endroid.conf` and it can be found in the source at
+`etc/endroid.conf`. The settings that must be added to the config file are details of an XMPP account for !EnDroid to use (free accounts can be created easily e.g. from
+[[http://comm.unicate.me/|comm.unicate.me]]). 
+
+ Note: '''Do not use your own account''' as !EnDroid will cut down its contact list to users listed in the config file.
+
+Other settings that should be set are `users` - the list of users !EnDroid will communicate with - remember to add yourself to this and `rooms` the list of rooms !EnDroid will join. For more details
+on configuration see [[../Configuration|configuration]].
+
+= Running EnDroid =
+
+ * If you installed !EnDroid, you should be able to run it by typing `endroid` into the console.
+ * If you pulled the source, run !EnDroid from within the `src` directory with `./endroid.sh`
+ * See `-h` for full list of command line arguments, some key ones are:
+   * `<config-file>` - specify an alternative config file.
+   * `[-l|--level] <log-level>` - specify the verbosity of the console log (lower is more verbose)
+   * `[-L|--logfile] <log-file>` - redirect the console logging to a file.
+   * `[-t|--logtraffic]` -  if `-t` is present, `twisted` will log all the raw message xml to the file log.
+
+See the [[../Debugging|debugging page]] for more details on logging and `Manhole`.
+
+If you encounter any bugs please report them at [[https://bugs.launchpad.net/endroid|EnDroid launchpad]].
+
+Happy Droiding!
+
+= What Next? =
+
+Write some plugins to add some new functionality! See the [[../PluginTutorial|plugin tutorial]] to find out how easy it is.
+

=== renamed file 'doc/Index' => 'doc/wiki/Index'
--- doc/Index	2012-08-27 23:19:45 +0000
+++ doc/wiki/Index	2013-08-14 10:10:05 +0000
@@ -2,12 +2,15 @@
 
 = EnDroid =
 
-EnDroid is a modular XMPP bot platform written in Python and built upon the Twisted framework.
+!EnDroid is a modular XMPP bot platform written in Python and built upon the Twisted framework.
 
 == Documentation ==
 
- * [[EnDroid/Installation|Installation]]
- * [[EnDroid/Configuration|Configuration]]
- * [[EnDroid/WritingPlugins|WritingPlugins]]
+ * [[/GettingStarted|Getting Started]]
+ * [[/Configuration|Configuration]]
+ * [[/PluginTutorial|Plugin Tutorial]]
+ * [[/Reference|API Reference]]
+ * [[/Debugging|Debugging]]
 
 <<Include(/BluePrints)>>
+

=== added file 'doc/wiki/PluginTutorial'
--- doc/wiki/PluginTutorial	1970-01-01 00:00:00 +0000
+++ doc/wiki/PluginTutorial	2013-08-14 10:10:05 +0000
@@ -0,0 +1,790 @@
+#acl EnsoftLander:read,write,delete,revert,admin All:read
+
+<<TableOfContents>>
+
+= Introduction =
+
+Over the course of this tutorial we will write a plugin for !EnDroid which plays a simple pass-the-bomb game over chat.
+
+A user should be able to create a bomb with a specified timer, then throw it to another user. The recipient should then be able to continue the process.
+
+When the timer expires the bomb should 'kill' its holder and award a kill to whoever lit the fuse.
+
+This plugin is command orientated - that is we will be using it in chat by typing commands to !EnDroid e.g. `bomb 15` to create a bomb with a 15 second timer. This suggests we use the Command plugin
+which simplifies this type of interaction.
+
+Links to the relevant sections of the !Reference page are at the bottom of each section of this tutorial.
+
+== Preface: Laying the ground work ==
+
+=== Getting EnDroid ===
+
+See: [[../GettingStarted#Installation|EnDroid installation]] for instructions on getting and setting up !EnDroid.
+
+We will be creating a plugin at `~/.endroid/plugins/passthebomb.py`. To get !EnDroid to load the plugin, make sure you have:
+
+{{{
+[room | group : * ]
+plugins = passthebomb,
+          endroid.plugins.command,
+# all the other plugins you want
+}}}
+
+See [[../Configuration|EnDroid configuration]] for more details on the config file.
+
+=== Debugging ===
+
+It is fairly probably that at some stage something will go wrong. For information about debugging problems, see: [[../Debugging|EnDroid debugging]].
+
+== A Plot: CommandPlugin ==
+
+Firstly we will get things set up so that our plugin responds to the keywords 'bomb', 'throw' and 'kills'.
+
+{{{#!highlight python
+from endroid.plugins.command import CommandPlugin
+
+class PassTheBomb(CommandPlugin):
+    # The help attribute will be displayed when 'help passthebomb' is 
+    # run provided that the help plugin is enabled.
+    help = "Pass the bomb game for EnDroid"
+
+    def cmd_bomb(self, msg, arg):
+        # Create a new bomb.
+        msg.reply("Made a new bomb with arguments '{}'".format(arg))
+
+    def cmd_throw(self, msg, arg):
+        # Throw the bomb to another person (or ourself if we fancy).
+        msg.reply("Throwing a bomb with arguments '{}'".format(arg))
+
+    def cmd_kills(self, msg, arg):
+        # How many kills do we have?
+        msg.reply("Getting killcount with arguments '{}'".format(arg))
+}}}
+
+The inheritance from `CommandPlugin` means that all methods beginning with `cmd_` are automagically registered e.g. `cmd_bomb` will be called when someone types `"bomb and then whatever else they
+want"`.
+
+Every `cmd_` function take two arguments: 
+ * msg - the Message object that triggered the call 
+ * arg - msg.body minus the first word (the name part of the cmd_<name> function)
+
+As it stands the plugin will do little except for reply to messages starting with the word 'bomb', 'throw' or 'kills' - but demonstrates simple response to commands.
+
+=== Aside: Plugin and CommandPlugin ===
+
+The general class that plugins inherit from is, unsurprisingly, `endroid.pluginmanager.Plugin` (either directly or via a subclass such as `CommandPlugin`). The `Plugin` class has access to
+`MessageHandler` and `UserManagement` objects via the `messagehandler` and `usermanagement` attributes. These objects provide access to functionality concerned with X'''MP'''P's '''m'''essaging and
+'''p'''resence facilities respectively.
+
+Additionally the `Plugin` class has methods by which a plugin can register a function with `messagehandler` such that the function will be called every time a specified type message is received, with
+the message as its argument. The primary such functions are:
+ * `register_muc_callback(<callable>)`
+ * `register_chat_callback(<callable>)`
+
+A simple example plugin:
+{{{#!highlight python
+from endroid.pluginmanager import Plugin
+
+class JFSullivan(Plugin):
+    def endroid_init(self):
+        self.register_chat_callback(self.do_harass)
+        self.register_muc_callback(self.do_harass)
+    
+    def do_harass(self, msg):
+        msg.reply("Purchase one of my fine umbrellas!")
+}}}
+This plugin registers for both muc and chat callbacks, so it's function is called whenever !EnDroid receives a muc or a chat message.
+
+`CommandPlugin` (`endroid.plugins.command.CommandPlugin`) inherits from `Plugin` and provides some helper features. It will automatically register class methods beginning with `cmd_`. It also provides
+extra options such as synonyms, registering for muc or chat only and providing help messages (via the `help` plugin). For these extras it looks for attributes on methods, e.g.:
+
+{{{#!highlight python
+from endroid.plugins.command import CommandPlugin
+
+class Umbrella(CommandPlugin):
+    def cmd_buy(self, msg, arg):
+        msg.reply("It will cost one thousand guineas")
+    cmd_buy.helphint = "When buying an umbrella, I recommend sheet steel"
+    cmd_buy.muc_only = True  # Can only be called from a group chat.
+    # cmd_buy.chat_only = True  # Can only be called from a single-user chat.
+    # messages starting with buy, purchase or acquire will call this function.
+    cmd_buy.synonyms = ("purchase", "acquire") 
+}}}
+
+  '''Note:''' A function registered with the Plugin class's `register` methods will be called with a __single__ argument - the message that caused it to be called. A `cmd_` function in a
+`CommandPlugin` derived class will be called with __two__ arguments: the message that caused it to be called, and the message's body stripped of the first word (which, as mentioned above, will have
+been the name of the function minus the `cmd_`.
+
+
+Full reference for `Plugin`: 
+ * [[../Reference#Plugin|EnDroid reference: plugin]]
+
+== Lighting the Fuse: Cron, Messagehandler ==
+
+Back to the Bomb plugin. We have got the plugin responding to commands but now we want to actually arm the bomb.
+
+`Cron` is !EnDroid's event scheduler. It provides methods to schedule future events, and allows persistency - i.e. events that will be remembered should !EnDroid undergo a restart. We will use it
+explode our bombs at suitable (or unsuitable, depending on who is holding the bomb) times. The `Cron` singleton object is accessible via `self.cron`.
+
+The scheduling of functions with `Cron` is a two stage process. Firstly we register a callable with `Cron` against a registration string: `register(callable, registration_name)`. Once this is done, we
+can use either `setTimeout(time, registration_name, parameters)` or `doAtTime(time, locality, registration_name, parameters)` to tell `Cron` to call the function at some point in the future
+(localities are as used by `pytz.timezone`).
+
+  '''Note:''' Registration names must be __globally__ unique (across all plugins), this is the purpose of the `get_id` function in the code below.
+
+{{{#!highlight python
+from endroid.cron import Cron
+
+class Bomb(object):
+    ID = 0
+    def __init__(self, source, fuse, plugin):
+        self.source = source  # The user who lit the fuse.
+        self.user = source  # Our current bearer.
+        self.plugin = plugin  # Plugin instance we belong to.
+        self.history = set()  # All our bearers.
+
+        idstring = self.get_id()  # Get a unique registration_name.
+        plugin.cron.register(self.explode, idstring)
+        # Schedule detonation with parameters = None.
+        plugin.cron.setTimeout(fuse, idstring, None)  
+
+    # This function is called by Cron and given an argument. We don't need an 
+    # argument so just ignore it.
+    def explode(self, _):
+        # Last argument of send_chat is the new message's source which defaults
+        # to None and is non-essential (it is used by the Message.reply methods
+        # and is visible to filters but neither of these are important to us).
+        self.plugin.messagehandler.send_chat(self.user, "BOOM!", None)
+
+    @classmethod
+    def get_id(cls):
+        # Generate a unique id string to register our explode method against.
+        result = Bomb.ID
+        cls.ID += 1
+        return "bomb" + str(result)
+
+
+class PassTheBomb(CommandPlugin):
+    ...
+    def cmd_bomb(self, msg, arg):
+        holder = msg.sender
+        try:
+            # Read a time from the first word of arg.
+            time = float(arg.split(' ', 1)[0])
+            # A new Bomb with the message sender as the source.
+            Bomb(msg.sender, time, self)
+            msg.reply("Sniggering evilly, you light the fuse...")
+        # Provision for a failure to read a time float.
+        except ValueError:
+            msg.reply("You struggle with the matches")
+}}}
+
+Now we can type `'bomb 5'` into chat and 5 seconds later (or so) it will explode.
+
+We have used the `messagehandler.send_chat` function here as the `Bomb` object has no access to a `Message` object to reply to. We will see the `messagehandler.send_muc` function shortly. The
+`MessageHandler` object is an abstraction of X'''M'''PPs '''messaging''' protocols as well as providing methods to register message callbacks (in our example these are hidden behind `CommandPlugin`)
+and to send messages in single and multi user chats.
+
+Full reference for `Cron`: 
+ * [[../Reference#Cron|EnDroid reference: Cron]]
+Full reference for `MessageHandler`: 
+ * [[../Reference#MessageHandler.2C_Message|EnDroid reference: MessageHandler]]
+
+== Throwing the Bomb: Usermanagement ==
+
+Now we will add the (important) ability to throw the bomb to another user. We will use the `UserManagement` object to check if our target is online.
+
+{{{#!highlight python
+from collections import defaultdict
+
+class Bomb(object):
+    ...
+    def __init__(self, source, fuse, plugin):
+        ...  # As before.
+        # Updating the user will now be controlled by our throw method
+        self.user = None  
+        ...
+
+    def explode(self, _):
+        self.plugin.messagehandler.send_chat(self.user, "BOOM!", self.plugin)
+        self.plugin.bombs[self.user].discard(self)  # This bomb is done
+
+    def throw(self, next_user):
+        # Remove this bomb from our current user.
+        self.plugin.bombs[self.user].discard(self)
+
+        self.history.add(next_user)
+        self.user = next_user
+
+        # Add it to the new user.
+        self.plugin.bombs[self.user].add(self)
+
+
+class PassTheBomb(CommandPlugin):
+    help = ...
+    bombs = defaultdict(set)  # A dictionary of which users have bombs
+
+    ...
+
+    def cmd_bomb(self, msg, arg):
+        holder = msg.sender
+        try:
+            # Read a time from the first word of arg.
+            time = float(arg.split(' ', 1)[0])
+            # A new Bomb with the message sender as the source, passed to 
+            # msg.sender.
+            Bomb(msg.sender, time, self).throw(msg.sender)   
+        ...
+
+    def cmd_throw(self, msg, arg):
+        target = arg.split(' ')[0]
+        # Check if the target is online.
+        if not target in self.usermanagement.get_available_users():
+            msg.reply("You look around but can't spot your target")
+        # Check if we actually have a bomb.
+        elif not self.bombs[msg.sender]:
+            msg.reply("You idly throw your hat, wishing you had something "
+                       "more 'splodey")
+        else:   
+            self.bombs[msg.sender].pop().throw(target)
+            msg.reply("You throw the bomb!")
+            # Let the target know we've thrown the bomb at him!
+            self.messagehandler.send_chat(target, "A bomb lands by your feet!")
+}}}
+
+
+`Usermanagement` is an abstraction of the XM'''P'''Ps '''presence'''  protocols. It provides a number of user management functions including:
+ * `get_[registered|available]_users(name=None)` - returns an iterable of users registered with/available in the room/group name, or in !EnDroid's contact list if name is None (in the code above we
+ * have used the `get_available_users(None)` to find the users online in our contact list)
+ * `get_[?available]_[rooms|groups](user)` - returns an iterable of rooms/groups the specified user is available/registered in.
+
+Now let us add some more interesting explosion reporting, utilising the second of the two above methods.
+
+{{{#!highlight python
+class Bomb(object):
+    ...
+    def explode(self, _):
+        # Some shorthands.
+        get_rooms = self.plugin.usermanagement.get_available_rooms
+        send_muc = self.plugin.messagehandler.send_muc
+        send_chat = self.plugin.messagehandler.send_chat
+
+        msg_explode = "!!!BOOM!!!"
+        msg_farexplode = "You hear a distant boom"
+        msg_kill = "{} was got by the bomb"
+
+        rooms = get_rooms(self.user)
+        for room in rooms:
+            # Let everyone in a room with self.user hear the explosion.
+            send_muc(room, msg_explode, self.plugin)
+            send_muc(room, msg_kill.format(self.user), self.plugin)
+
+        # Alert those who passed the bomb that it has exploded.
+        for user in self.history:
+            if user == self.user:
+                send_chat(self.user, msg_explode, self.plugin)
+                send_chat(self.user, msg_kill.format("You"), self.plugin)
+            else:
+                send_chat(user, msg_farexplode, self.plugin)
+                send_chat(user, msg_kill.format(self.user), self.plugin)
+
+        self.plugin.bombs[self.user].discard(self)
+}}}
+
+We broadcast the explode message in any room the victim is present in (`get_rooms(self.user)`) using `messagehandler`'s send_muc method and alert other users in the bomb's history. We also send a kill
+notice to all users in the history (note that any grammatical imperfections are features, not bugs).
+
+Full reference for `UserManagement`: 
+ * [[../Reference#UserManagement|EnDroid reference: UserManagement]]
+
+=== Aside: Plugin Scoping ===
+
+Note that we have used a class variable to store the dictionary of bombs.
+
+In !EnDroid, a seperate instance of each plugin is instantiated in each room/for each usergroup. This means that if plugins in seperate environments want to share information, they must use class
+variables.
+
+== A Criminal Record: Database ==
+
+`Database` is the second main utility class !EnDroid provides. It wraps an SQL database. We will use it to store kill-counts.
+
+{{{#!highlight python
+from endroid.database import Database
+
+DB_NAME = "PTB"
+DB_TABLE = "PTB"
+
+class Bomb(object):
+    ...
+    def explode(self, _):
+        ...
+        self.plugin.register_kill(self.source)   # Register the kill in the database.
+        self.plugin.bombs[self.user].discard(self)
+
+class PassTheBomb(CommandPlugin):
+    ...
+    def endroid_init(self):
+        # Note that this will either create a new database if none with name 
+        # DB_NAME exists, or open an existing one.
+        self.db = Database(DB_NAME)
+        # If we haven't already setup the database then do so.
+        if not self.db.table_exists(DB_TABLE):
+            # Create a table with fields 'user' and 'kills'.
+            self.db.create_table(DB_TABLE, ("user", "kills"))
+
+    def cmd_kills(self, msg, arg):
+        # Retrieve the users kill count.
+        kills = self.get_kills(msg.sender)
+        # self.place_name is the address of the room or name of the group this 
+        # plugin is active in.
+        nick = self.usermanagement.get_nickname(msg.sender, self.place_name)
+        level = self.get_level(kills)
+
+        text = "{} the {} has {} kill".format(nick, level, kills) 
+        text += ("" if kills == 1 else "s")
+        msg.reply(text)
+
+    def register_kill(self, user):
+        kills = self.get_kills(user)
+        if kills:
+            # Change the value of 'kills' to kills+1 in table rows where the
+            # field 'user' has value user.
+            r = self.db.update(DB_TABLE, {'kills': kills+1}, {'user': user})
+            assert r == 1  #  Exactly 1 row should be updated
+        else:
+            # The user is not registered in the database - so create a new 
+            # registration for them with their first kill stored.
+            self.db.insert(DB_TABLE, {'user': user, 'kills': 1})
+
+    def get_kills(self, user):
+        # Look in DB_TABLE for the 'kills' field in entries whose 'user' field 
+        # is user.
+        # Returns a list of dictionaries, each with keys: _endroid_unique_id 
+        # (always included but which we can ignore) and 'kills' - which we want.
+        results = self.db.fetch(DB_TABLE, ['kills'], {'user': user})
+        if len(results) == 0:  # The user is not registered in the database.
+            return 0
+        else:
+            # Get the first dictionary in results and extract the value of 
+            # 'kills' from it.
+            return results[0]['kills']
+
+    @staticmethod
+    def get_level(kills):
+        if kills < 5:
+            level = 'novice'
+        elif kills < 15:
+            level = 'apprentice'
+        elif kills < 35:
+            level = 'journeyman'
+        elif kills < 65:
+            level = 'expert'
+        elif kills < 100:
+            level = 'master'
+        else:
+            level = 'grand-master'
+        return level
+}}}
+
+We have used the `endroid_init` method, which is called by !EnDroid's plugin management system when a plugin is loaded. Here we use it to set up a database.
+
+The use of the database is fairly straightforward, in general methods take parameters table_name, options_list_or_dict and conditions_dictionary. Their parameters are internally converted into strings
+and passed to an SQL query which does the gruntwork.
+
+So far, we have a fully functional plugin which does everything we set out to do. However there are still a couple of things to be done.
+
+Full reference for `Database`: 
+ * [[../Reference#Database|EnDroid reference: Database]]
+
+== Umbrellas: For when it rains (bombs) ==
+
+There is a problem with the plugin as it stands. If a user does not want to take part in the game (however inconceivable this may seem...) he/she has no options.
+
+We will remedy these problems by giving all users patented JF Sullivan umbrellas, which they can unfurl to protect themselves and furl to join in the game. By default a user's umbrella is unfurled
+(i.e. we operate on an opt-in policy).
+
+When an umbrella is unfurled, the user should not be able to light a new bomb, nor throw an existing bomb, nor have a bomb thrown at them.
+
+Most of the changes made to the code to introduce this feature are just Python, so will not be explained in any detail.
+
+{{{#!highlight python
+from collections import namedtuple
+
+class User(object):
+    # A class to represent a player of the game.
+    __slots__ = ('name', 'kills', 'shield')
+    def __init__(self, name, kills=0, shield=True):
+        self.name = name
+        self.kills = kills
+        self.shield = shield
+
+    def __repr__(self):
+        return "User(name={}, kills={}, shield={})".format(self.name, 
+                                                           self.kills, 
+                                                           self.shield)
+
+...
+
+class PassTheBomb(CommandPlugin):
+    ...
+    users = dict()  # A dictionary of registered game players.
+
+    def endroid_init(self):
+        ...
+            self.db.create_table(DB_TABLE, ('user', 'kills'))
+        else:
+            # Make a local copy of the registration database.
+            data = self.db.fetch(DB_TABLE, ['user', 'kills'])
+            # Data is a list of dictionaries, each one representing a row in 
+            # the database.
+            for dct in data:
+                self.users[dct['user']] = User(dct['user'], dct['kills'])
+
+    def cmd_furl_umbrella(self, msg, arg):
+        """
+        This is how a user enters the game - allows them to be targeted
+        and to create and throw bombs.
+
+        """
+        user = msg.sender
+        if not self.get_shielded(user):
+            msg.reply("Your umbrella is already furled!")
+        else:
+            if self.get_registered(user):
+                self.users[user].shield = False
+            else:  # They are not - register them.
+                self.db.insert(DB_TABLE, {'user': user, 'kills': 0})
+                self.users[user] = User(user, kills=0, shield=False)
+            msg.reply("You furl your umbrella!")
+
+    def cmd_unfurl_umbrella(self, msg, arg):
+        """A user with an unfurled umbrella cannot create or receive bombs"""
+        user = msg.sender
+        if self.get_shielded(user):
+            msg.reply("Your umbrella is already unfurled!")
+        else:
+            # To get user must not have been shielded ie they must have furled
+            # so they will be in the database.
+            self.users[user].shield = True
+            msg.reply("You unfurl your umbrella! No bomb can reach you now!")
+
+
+    def cmd_bomb(self, msg, arg):
+        """
+        Create a bomb with a specified timer, eg: 'bomb 1.5' for a 1.5 second
+        fuse.
+
+        """
+
+        holder = msg.sender
+        if self.get_shielded(holder):
+            return msg.reply("Your sense of honour insists that you furl your "
+                              "umbrella before lighting the fuse")
+        # Otherwise get a time from the first word of arg.
+        ...
+
+    def cmd_throw(self, msg, arg):
+        """Throw a bomb to a user, eg: 'throw [e-mail]'."""
+        target = arg.split(' ')[0]
+        if not self.bombs[msg.sender]:  # Do we even have a bomb?
+            msg.reply("You idly throw your hat, wishing you had something more"
+                      "'splodey")
+        elif self.get_shielded(msg.sender):  # Must be vulnerable while throwing.
+            msg.reply("You notice that your unfurled umbrella would hinder "
+                       "your throw.")
+        elif not target in self.usermanagement. ...
+        elif self.get_shielded(target):  # Target registered/vulnerable?
+            msg.reply("You see your target hunkered down under their umbrella. "
+                       "No doubt a bomb would have no effect on that "
+                       "monstrosity.")
+        else:  ...
+
+    ...
+
+    def register_kill(self, user):
+        ...
+        self.users[user].kills += 1  # update our local copy
+
+    # Use our local copy of database information to minimise database access.
+    def get_kills(self, user):
+        return self.users[user].kills if user in self.users else 0
+
+    def get_shielded(self, user):
+        return self.users[user].shield if user in self.users else True
+
+    def get_registered(self, user):
+        return user in self.users
+
+    @staticmethod
+    def get_level(kills):
+        ...
+}}}
+
+There are a few things here to note.
+
+First and foremost: database calls are '''synchronous''' i.e. !EnDroid will grind to a halt (briefly) each time the database is accessed. In the above code, we have kept only 'kills' recorded in the
+database (we could have kept 'shield' there too but that would mean many more read/writes). As a result things will be faster but if !EnDroid restarts for any reason, all users umbrellas will become
+unfurled (but this is not a particular problem).
+
+Secondly - it is generally a good idea to design plugins to be at least somewhat '''spam-resistent'''. In this case we have used an opt-in policy (an !EnDroid user will know nothing of the PTB plugin
+until he/she furls his/her umbrella) and have provided an option to silence the plugin (by unfurling it again).
+
+Thirdly we see some more of the functionality of !CommandPlugin. The functions `cmd_[?un]furl_umbrella` will respond to messages: "[?un]furl umbrella" i.e. require two words to activate. This idea
+extends indefinitely, it would be completely possible to create the command: 
+`cmd_go_and_buy_a_new_umbrella_mine_is_somewhat_battlescarred`
+which would respond to the message "go and buy ...".
+
+= The Full Code =
+
+A few minor changes have been made below - mostly to do with commenting and report strings.
+
+{{{#!highlight python
+from endroid.plugins.command import CommandPlugin
+from endroid.cron import Cron
+from collections import defaultdict, namedtuple
+from endroid.database import Database
+
+DB_NAME = "PTB"
+DB_TABLE = "PTB"
+
+class User(object):
+    __slots__ = ('name', 'kills', 'shield')
+    def __init__(self, name, kills=0, shield=True):
+        self.name = name
+        self.kills = kills
+        self.shield = shield
+
+    def __repr__(self):
+        return "User(name={}, kills={}, shield={})".format(self.name, self.kills, self.shield)
+
+class Bomb(object):
+    ID = 0
+    def __init__(self, source, fuse, plugin):
+        self.source = source  # Who lit the bomb?
+        self.user = None  # Our current holder.
+        self.plugin = plugin  # Plugin instance we belong to.
+        self.history = set()  # Who has held us?
+
+        idstring = self.get_id()  # Get a unique registration_name.
+        plugin.cron.register(self.explode, idstring)
+        plugin.cron.setTimeout(fuse, idstring, None)  # Schedule detonation.
+
+    # This function is called by Cron and given an argument. We don't need an
+    # argument so just ignore it.
+    def explode(self, _):
+        # Some shorthands.
+        get_rooms = self.plugin.usermanagement.get_available_rooms
+        send_muc = self.plugin.messagehandler.send_muc
+        send_chat = self.plugin.messagehandler.send_chat
+
+        msg_explode = "!!!BOOM!!!"
+        msg_farexplode = "You hear a distant boom"
+        msg_kill = "{} was got by the bomb"
+
+        rooms = get_rooms(self.user)
+        for room in rooms:
+            # Let everyone in a room with self.user here the explosion.
+            send_muc(room, msg_explode)
+            send_muc(room, msg_kill.format(self.user))
+
+        # Alert those who passed the bomb that it has exploded.
+        for user in self.history:
+            if user == self.user:
+                send_chat(self.user, msg_explode)
+                send_chat(self.user, msg_kill.format("You"))
+            else:
+                send_chat(user, msg_farexplode)
+                send_chat(user, msg_kill.format(self.user))
+
+        self.plugin.register_kill(self.source)
+        self.plugin.bombs[self.user].discard(self)
+
+
+    def throw(self, user):
+        # Remove this bomb from our current user.
+        self.plugin.bombs[self.user].discard(self)
+
+        self.history.add(user)
+        self.user = user
+
+        # Add it to the new user.
+        self.plugin.bombs[self.user].add(self)
+
+    @classmethod
+    def get_id(cls):
+        # Generate a unique id string to register our explode method against.
+        result = Bomb.ID
+        cls.ID += 1
+        return "bomb" + str(result)
+
+
+class PassTheBomb(CommandPlugin):
+    help = "Pass the bomb game for EnDroid"
+    bombs = defaultdict(set)  # Users : set of bombs.
+    users = dict()  # User strings : User objects.
+
+    def endroid_init(self):
+        self.db = Database(DB_NAME)
+        if not self.db.table_exists(DB_TABLE):
+            self.db.create_table(DB_TABLE, ('user', 'kills'))
+        else:
+            # Make a local copy of the registration database.
+            data = self.db.fetch(DB_TABLE, ['user', 'kills'])
+            for dct in data:
+                self.users[dct['user']] = User(dct['user'], dct['kills'])
+
+    def cmd_furl_umbrella(self, msg, arg):
+        """
+        This is how a user enters the game - allows them to be targeted
+        and to create and throw bombs.
+
+        """
+        user = msg.sender
+        if not self.get_shielded(user):
+            msg.reply("Your umbrella is already furled!")
+        else:
+            if self.get_registered(user):
+                self.users[user].shield = False
+            else:  # They are not - register them.
+                self.db.insert(DB_TABLE, {'user': user, 'kills': 0})
+                self.users[user] = User(user, kills=0, shield=False)
+            msg.reply("You furl your umbrella!")
+    cmd_furl_umbrella.helphint = ("Furl your umbrella to participate in the "
+                                  "noble game of pass the bomb!")
+
+    def cmd_unfurl_umbrella(self, msg, arg):
+        """A user with an unfurled umbrella cannot create or receive bombs."""
+        user = msg.sender
+        if self.get_shielded(user):
+            msg.reply("Your umbrella is already unfurled!")
+        else:
+            # To get user must not have been shielded ie they must have furled
+            # so they will be in the database.
+            self.users[user].shield = True
+            msg.reply("You unfurl your umbrella! No bomb can reach you now!")
+    cmd_unfurl_umbrella.helphint = ("Unfurl your umbrella to cower from the "
+                                    "rain of boms!")
+
+    def cmd_bomb(self, msg, arg):
+        """Create a bomb with a specified timer."""
+
+        holder = msg.sender
+        if self.get_shielded(holder):
+            return msg.reply("Your sense of honour insists that you furl your "
+                              "umbrella before lighting the fuse")
+        # Otherwise get a time from the first word of arg.
+        try:
+            time = float(arg.split(' ', 1)[0])
+            # Make a new bomb and throw it to its creator.
+            Bomb(msg.sender, time, self).throw(msg.sender)
+            msg.reply("Sniggering evilly, you light the fuse...")
+        # Provision for a failure to read a time float...
+        except ValueError:
+            msg.reply("You struggle with the matches")
+    cmd_bomb.helphint = ("Light the fuse!")
+
+    def cmd_throw(self, msg, arg):
+        """Throw a bomb to a user, eg: 'throw [e-mail]'"""
+        target = arg.split(' ')[0]
+        # We need a bomb to throw.
+        if not self.bombs[msg.sender]: 
+            msg.reply("You idly throw your hat, wishing you had something " 
+                       "rounder, heavier and with more smoking fuses.")
+        # Need our umbrella to be furled.
+        elif self.get_shielded(msg.sender):
+            msg.reply("You notice that your unfurled umbrella would hinder "
+                       "your throw.")
+        # Check that target is online.
+        elif not target in self.usermanagement.get_available_users():
+            msg.reply("You look around but cannot spot your target")
+        elif self.get_shielded(target):  # Target registered/vulnerable?
+            msg.reply("You see your target hunkered down under their umbrella. "
+                       "No doubt a bomb would have little effect on that "
+                       "monstrosity.")
+        else:
+            self.bombs[msg.sender].pop().throw(target)
+            msg.reply("You throw the bomb!")
+            self.messagehandler.send_chat(target, "A bomb lands by your feet!")
+    cmd_throw.helphint = ("Throw a bomb!")
+
+    def cmd_kills(self, msg, arg):
+        kills = self.get_kills(msg.sender)
+        nick = self.usermanagement.get_nickname(msg.sender, 
+                                                     self.place_name)
+        level = self.get_level(kills)
+
+        text = "{} the {} has {} kill".format(nick, level, kills)
+        text += ("" if kills == 1 else "s")
+        msg.reply(text)
+    cmd_kills.helphint = ("Receive and gloat over you score!")
+
+    def register_kill(self, user):
+        kills = self.get_kills(user)
+        # Change the value of 'kills' to kills+1 in the row where 'user' = user.
+        self.users[user].kills += 1
+        self.db.update(DB_TABLE, {'kills': kills+1}, {'user': user})
+
+    def get_kills(self, user):
+        return self.users[user].kills if user in self.users else 0
+
+    def get_shielded(self, user):
+        return self.users[user].shield if user in self.users else True
+
+    def get_registered(self, user):
+        return user in self.users
+
+    @staticmethod
+    def get_level(kills):
+        if kills < 5:
+            level = 'novice'
+        elif kills < 15:
+            level = 'apprentice'
+        elif kills < 35:
+            level = 'journeyman'
+        elif kills < 65:
+            level = 'expert'
+        elif kills < 100:
+            level = 'master'
+        else:
+            level = 'grand-master'
+        return level
+
+}}}
+
+= Extras =
+
+== Adding Configuration ==
+
+We can add configuration to our plugin by adding a section in `endroid.conf`:
+
+{{{
+[room | group : * : pconfig : endroid.plugins.passthebomb]
+my_string = this is a string
+my_int = 123
+my_list = this, has, commas, so, is, a, list
+my_list2 = 1
+           2
+           3
+# This will be ignored as long as # is in the first column.
+           4
+           5
+}}}
+
+These variables will now be available in the `self.vars` dictionary, which will look like this:
+
+{{{#!highlight python
+self.vars = {
+ 'my_string' : 'this is a string',
+ 'my_int' : 123,
+ 'my_list': ['this', 'has', 'commas', 'so', 'is', 'a', 'list']
+ 'my_list2': [1,2,3,4,5]
+}
+}}}
+
+See [[../Configuration|EnDroid configuration]] for more details on the format of the config file.
+
+= Further Reading =
+
+ * [[../Reference|EnDroid reference]]
+ * [[http://www.bartitsu.org/index.php/2009/05/the-umbrella-a-misunderstood-weapon/|JFSullivan]]
+

=== added file 'doc/wiki/Reference'
--- doc/wiki/Reference	1970-01-01 00:00:00 +0000
+++ doc/wiki/Reference	2013-08-14 10:10:05 +0000
@@ -0,0 +1,557 @@
+#acl EnsoftLander:read,write,delete,revert,admin All:read
+
+<<TableOfContents>>
+
+This API reference will be split into three main parts.
+ Endroid core:: APIs for the Plugin class and classes directly accessible from that class. All plugins will be able to access all of this API with no extra work.
+ Utilities:: APIs provided by the Endroid modules Database (for persistent data storage) and Cron (for task scheduling) which plugins may import.
+ Helper Plugins:: !EnDroid plugins which are designed to be inherited from (e.g. {{{CommandPlugin}}} or 'imported' via {{{Plugin.get("endroid.plugins.<name>")}}} and provide useful extra
+functionality.
+
+= Glossary =
+ muc/chat:: A muc (Multi-User Chat) message is one sent in or to a room (group chat). A chat message is one sent to a single user.
+ jid:: The address of a user or room. This is a different format depending on the entity being addressed and plugins shouldn't need to know the format being used. However in case its useful it will
+be: {{{user@ho.s.t}}} for a single user, {{{[e-mail]}}} for a room and {{{[e-mail]/user_nickname}}} for a user in a room.
+
+= Core Endroid =
+
+API reference for the Plugin class and classes directly available to it. All plugins are expected to inherit from either {{{endroid.pluginmanager.Plugin}}} or a subclass of this class e.g.
+{{{endroid.plugins.CommandPlugin}}}.
+
+== Plugin ==
+
+{{{#!highlight python
+class Plugin(object):
+    """
+    All plugins are expected to subclass plugin in one way or another.
+
+    Attributes:
+     - usermanagment
+     - messagehandler
+       References to Endroid's usermanagment and messagehandler objects
+       through which further APIs may be called.
+     - cron
+       A reference to the Cron singleton through which task scheduling is available.   
+
+     - dependencies
+       Iterable of plugins this plugin requires to be loaded before it can be
+       activated by EnDroid.
+
+     - preferences
+       Iterable of plugins this plugin will use if they are available but does
+       not require.
+
+     - place
+       The environment the plugin is active in - either 'room' (muc) or 'group'
+       (single user chat - active in a user group).
+     - place_name
+       The name of the environment the plugin is active in - either a room's
+       address ([e-mail]) or the name of a user group.
+     
+     - vars
+       A dictionary of config options read from the section in EnDroid's
+       config file:
+       [ self.place_name : self.place : pconfig : <plugin_name> ]
+
+    """
+
+    def register_muc_callback(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    def register_chat_callback(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    """
+    Register a callback to be called when a muc or chat message is received.
+
+    - inc_self tells EnDroid whether it should do the callback on messages 
+    that EnDroid has sent itself.
+    - priority is unused by Endroid but accessible to plugins and measures the
+    importance of a message (lower numbers = more important).
+
+    """
+
+    def register_unhandled_muc_callback(self, callback, inc_self=False,
+                                       priority=PRIORITY_NORMAL):
+    def register_unhandled_chat_callback(self, callback, inc_self=False, 
+                                         priority=PRIORITY_NORMAL):
+    """
+    Unhandled callbacks are called by EnDroid when a message has not been
+    processed by any callbacks.
+
+    They called by a plugin via Message.unhandled(*args) (usually when the
+    plugin has tried to run its own callback but failed) and so the message has
+    not been handled.
+
+    """
+
+    # The following four methods register filter functions which take Message 
+    # objects and return bools.
+    # Callable should take a message and return a bool.
+    # If a filter returns False, the message will be dropped. A filter 
+    # may modify a Message object's attributes.
+    # Callable may alter the message by changing its attributes.
+
+    def register_muc_filter(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    def register_chat_filter(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    """Receive filters (can cause EnDroid to ignore the message)."""
+    
+    def register_muc_send_filter(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    def register_chat_send_filter(self, callback, inc_self=False, priority=PRIORITY_NORMAL):
+    """Send filters (can cause EnDroid to not send a message)."""
+
+    def get(self, plugin_name):
+    """
+    Load plugin called plugin_name (eg endroid.plugins.my_plugin).
+
+    This acts very much like import; it returns an object through which 
+    plugin_name's functions can be accessed.
+    Note that if get is used, plugin_name should be added to the plugin 
+    class's dependencies tuple.
+
+    """
+
+    def get_dependencies(self):
+    def get_preferences(self):
+    """
+    Return a full list of the plugin's dependencies/preferences.
+
+    This includes those of the plugins it depends on/prefers and so on 
+    down the chain.
+
+    """
+
+    def list_plugins(self):
+    """
+    Get an iterable of all the plugins active in this plugin's environment 
+    (a specific room or usergroup - not globally)."""
+
+}}}
+
+=== Plugin Scope ===
+
+Plugins are separately instantiated in each room they are configured in and for each user group. Bear in mind that if a plugin wishes to store data globally (across all rooms and user groups), a class
+variable should be used.
+
+Plugins can find out information about their environment via {{{self.place}}} and {{{self.place_name}}} which return the type of environment ({{{"room"}}} or {{{"group"}}}) and the name of the
+environment (e.g. {{{"[e-mail]"}}} or {{{"admins"}}}) respectively.
+
+== MessageHandler, Message ==
+
+APIs for !EnDroid's message functionality.
+
+{{{#!highlight python
+class MessageHandler(object):
+    """A class abstracting XMPP's message protocols."""
+
+    def send_muc(self, room, body, source=None, priority=PRIORITY_NORMAL):
+        """
+        Send a multi-user-chat message to the room. 
+
+        Source is optional. It is unused by EnDroid but visible to plugins
+        and filters (eg a filter may block all messages with a specified source)
+        Priority is not used internally but is available to plugins. 
+        PRIORITY_NORMAL = 0, the lower the number, the higher the priority.
+
+        """
+
+    def send_chat(self, user, body, source=None, priority=PRIORITY_NORMAL):
+        """
+        Send a single-user-chat message to the user with address user.
+
+        Other arguments are the same as send_muc.
+
+        """
+
+class Message(object):
+    """
+    Object representing a single message (muc or chat).
+
+    A Message object is passed by MessageHandler to any callbacks registered
+    via the Plugin.register_ commands.
+
+    Attributes:
+      - sender - a string representing the sender's userhost.
+      - sender_full - a string representing the sender's full jid.
+      Note: sender_full is used to reply to messages so that if a user is
+      online on more than one resource the reply will go to the right one.
+
+      - body - the text of the message.
+      - recipient - a string representing the address to send the message to
+      - priority - a number, lower = more important (unused by EnDroid, can
+      be accessed by plugins).
+
+    """
+
+    def reply(self, body):
+        """
+        Reply with a single or multi-user-chat message to self.sender.
+
+        The reply will have the same type as the received message, so replying
+        to a message in a room will reply to the whole room.
+
+        """
+
+    def reply_to_sender(self, body):
+        """
+        Reply with a single user chat to self.sender. 
+
+        Note the difference from reply - calling reply on a group message will 
+        send a group message, calling reply_to_sender on the same message will 
+        send a single user chat message to its sender.
+
+        """
+
+    def send(self):
+        """Send the Message to it's recipient."""
+
+    def unhandled(self, *args):
+        """
+        Notify the message that the caller hasn't handled it. This should only
+        be called by plugins that have registered as a handler (and thus have
+        incremented the handler count for this message).
+
+        This method takes arbitrary arguments so it can be used as deferred
+        callback or errback.
+
+        """
+}}}
+
+== UserManagement ==
+
+Note: all the get_ methods take a name string which is one of:
+ * The jid of a room
+ * The name of a usergroup
+ * None (in which case results will be looked for in !EnDroid's contact list)
+
+{{{#!highlight python
+class UserManagement(object):
+    """
+    A class abstracting XMPP's presence protocols.
+
+    In the get_ member functions, name (a userhost string e.g. [e-mail] or 
+    [e-mail]) specifies in which room or group to run a search. If it is
+    None, the search will be run on EnDroid's contact list (of rooms or users
+    depending on the function).
+
+    """
+
+    def get_users(self, name=None):
+        """Return an iterable of users registered with room/group name."""
+
+    def get_available_users(self, name=None):
+        """Return an iterable of users available in room/group name."""
+
+    def get_groups(self, user=None):
+        """Return an iterable of groups the user is registered with."""
+
+    def get_available_groups(self, user=None):
+        """Return an iterable of groups the user is present in."""
+
+    def get_rooms(self, user=None):
+        """Return an iterable of rooms the user is registered with."""
+
+    def get_available_rooms(self, user=None):
+        """Return an iterable of rooms the user is present in."""
+
+    def get_nickname(self, user, place=None):
+        """
+        Given a user jid (user@ho.s.t) return the user's nickname in place,
+        or if place is None (default), the user part of the jid.
+
+        """
+
+    def invite(self, user, room, reason=None):
+        """
+         Invite a user to a room.
+
+        Will only send invitation if the user is in our contact list and online,
+        and if the user is registered in the room but not currently in it.
+
+        Returns a tuple (success, report-message).
+
+        Report message may be:
+            "User not registered"
+            "User not available"
+            "Room not registered"
+            "User not registered in room"
+            "User already in room"
+            "Invitation sent"
+        """
+}}}
+
+= Utilities =
+
+API reference for !EnDroid's utility classes.
+
+== Database ==
+
+A wrapper around an sqlite3 database.
+
+{{{#!highlight python
+class Database(object):
+    """
+    This is wrapper around an sqlite3 database. Note that all accesses
+    are _synchronous_, so should be minimised. (It is likely that in
+    the future all accesses will be made using twisted.enterprise.adbapi
+    which is asynchronous).
+
+    """
+    def __init__(self, modName):
+    """Create a new database with name=modName in the Database singleton."""
+
+    def create_table(self, name, fields):
+    """
+    Create a new table in the database called 'name' and containing fields 
+    'fields' (an iterable of strings giving field titles).
+
+    """
+
+    def table_exists(self, name):
+    """Check to see if a table called 'name' exists in the database."""
+
+    def insert(self, name, fields):
+    """
+    Insert a row into table 'name'.
+    
+    Fields is a dictionary mapping field names (as defined in 
+    create_table) to values.
+
+    """
+
+    def fetch(self, name, fields, conditions={}):
+    """
+    Get data from the table 'name'. 
+
+    Returns a list of dictionaries mapping 'fields' to their values, one 
+    dictionary for each row which satisfies a condition in conditions.
+
+    Conditions is a dictionary mapping field names to values. A result
+    will only be returned from a row if its values match those in conditions.
+
+    E.g.: conditions = {'user' : JoeBloggs} 
+    will match only fields in rows which have JoeBloggs in the 'user' field.
+
+    """
+
+    def count(self, name, conditions):
+    """Return the number of rows in table 'name' which satisfy conditions."""
+
+    def delete(self, name, conditions):
+    """Delete rows from table 'name' which satisfy conditions."""
+
+    def update(self, name, fields, conditions):
+    """
+    Update rows in table 'name' which satisfy conditions. 
+
+    Fields is a dictionary mapping the field names to their new values.
+
+    """
+
+    def empty_table(self, name):
+    def delete_table(self, name):
+    """Remove all rows from/delete table 'name'."""
+}}}
+
+== Cron ==
+
+!EnDroid's task scheduling service.
+
+{{{#!highlight python
+class Cron(object):
+    def get():
+    """
+    Return a reference to the Cron singleton. All below functions can be 
+    accessed via Cron.get().<function>(args).
+
+    """
+
+class CronSing(object):
+    """The singleton returned by Cron.get()."""
+
+    def register(self, function, reg_name, persistent=True):
+    """
+    Register the callable 'function' against 'reg_name'. Note that 'reg_name'
+    must be globally unique. Allows function to be scheduled with doAtTime or
+    setTimeout.
+
+    If persistent is False, remoteTask(reg_name) will be called before the
+    the function is registered (so across a restart of EnDroid, the stored
+    tasks will be forgotten).
+
+    """
+
+    def doAtTime(self, time, locality, reg_name, params):
+    """
+    Schedule the callable registered against 'reg_name' to be called 
+    with 'params' (which must be picklable) at locality time 'time'. 
+    (Localities are from pytz.timezone).
+
+    """
+
+    def setTimeout(self, timedelta, reg_name, params):
+    """
+    Schedule the callable to be called in after 'timedelta'.
+
+    Timedelta may be a datetime.timedelta object or a real number representing 
+    the number of seconds to wait. Negative or zero values will trigger almost
+    immediately.
+
+    """
+
+    def removeTask(self, reg_name):
+        """Remove any scheduled tasks registered with reg_name."""
+
+    def getAtTimes(self):
+        """
+        Return a string showing the registration names of functions scheduled
+        with doAtTime and the amount of time they will be called in.
+
+        """
+
+    def getTimeouts(self):
+        """
+        Return a string showing the registration names of functions scheduled
+        with setTimeout and the amount of time they will be called in.
+
+        """
+}}}
+
+
+= Helper Plugins =
+
+API reference for plugins designed to be used by other plugins.
+
+All of these plugins are located at {{{endroid.plugins.<plugin_name>}}}
+
+== Command ==
+
+Plugins should inherit from {{{CommandPlugin}}} or use {{{self.comm = self.get("endroid.plugins.command")}}} to use {{{Command}}}'s methods.
+
+{{{#!highlight python
+"""
+Helper plugin to handle command registrations by other plugins. This is
+the main avenue by which plugins are expected to handle incoming messages
+and it is expected most plugins will depend on this.
+
+"""
+
+class CommandPlugin(Plugin):
+    """
+    Parent class for simple command-driven plugins.
+
+    Such plugins don't need to explicitly register their commands. Instead, they
+    can just define methods prefixed with "cmd_" and they will automatically be
+    registered. Any additional underscores in the method name will be converted
+    to spaces in the registration (so cmd_foo_bar is registered as ('foo',
+    'bar')).
+
+    In addition, certain options can be passed by adding fields to the methods:
+    - hidden: don't show the command in help if set to True.
+    - synonyms: an iterable of alternative keyword sequences to register the
+        method against. All synonyms are hidden.
+    - helphint: a hint to print after the keywords in help output.
+    - muc_only or chat_only: register for only chat or muc messages (default is
+        both).
+
+    """
+
+class Command(Plugin):
+    """
+    The instance of this class active in a plugin's room/group is 
+    returned by a Plugin.get("endroid.plugins.command") call.
+
+    This class makes it possible to access the functionality of CommandPlugin
+    without the inheritance.
+    
+    """
+
+    def register_muc(self, callback, command, helphint="", hidden=False,
+                     synonyms=()):
+        """Register a new handler for MUC messages."""
+
+    def register_chat(self, callback, command, helphint="", hidden=False,
+                      synonyms=()):
+        """Register a new handler for chat messages."""
+
+    def register_both(self, callback, command, helphint="", hidden=False,
+                      synonyms=()):
+        """Register a handler for both MUC and chat messages."""
+}}}
+
+For an example usecase look at the {{{invite}}} plugins.
+
+== HTTPInterface ==
+
+Start a webserver, allow callback registrations on URL paths, and route requests to callbacks.
+
+{{{#!highlight python
+class HTTPInterface(Plugin):
+    """
+    The actual plugin class. This may be instantiated multiple times, but is
+    just a wrapper around a HTTPInterfaceSingleton object.
+
+    """
+
+    def register_regex_path(self, plugin, callback, path_regex):
+        """
+        Register a callback to be called for requests whose URI matches:
+           http://<server>/<plugin name>/<regex>[?<args>]
+
+        Callback arguments:
+            request: A twisted.web.http.Request object.
+
+        """
+
+    def register_path(self, plugin, callback, path_prefix):
+        """
+        Register a callback to be called for requests whose URI matches:
+            http://<server>/<plugin name>/<prefix>[?<args>]
+
+        Or:
+            http://<server>/<plugin name>/<prefix>/<more path>[?<args>]
+
+        Or if the prefix is the empty string:
+            http://<server>/<plugin name>/<more path>[?<args>]
+
+        """
+}}}
+
+=== Remote Plugin, endroid_echo script ===
+
+For an example usecase look at the remote plugin, this calls: {{{register_path(self, self.http_request_handler, '')}}}. This listens on {{{http://<ip address>:8880/remote/}}} by default, where a form
+can be filled in to send an !EnDroid user a chat message. You can change the port number with the following configuration file option:
+
+{{{
+# HTTP port for remote messaging
+[ group | room : * : pconfig : endroid.plugins.httpinterface ]
+http_port = 8881
+}}}
+
+You also need the {{{httpinterface}}} and {{{remote}}} plugins to be loaded.
+
+The {{{endroid_echo}}} script (located at {{{/bin/endroid_echo}}} provides a method of sending a message to an !EnDroid user from the command line via the {{{remote}}} plugin. A user must specify the
+environment variables {{{ENDROID_REMOTE_KEY}}}, {{{ENDROID_REMOTE_USER}}} and {{{ENDROID_REMOTE_URL}}} and when the script runs (via {{{endroid_echo message_here}}} it will send the the message
+"message_here" to the user with JID {{{ENDROID_REMOTE_USER}}} provided that they have enabled the remote plugin (by typing {{{allow remote}}} to !EnDroid and receiving their key in response) and that
+{{{ENDROID_REMOTE_KEY}}} matches the user's remote plugin key. The default value for {{{ENDROID_REMOTE_URL}}} would be {{{http://127.0.0.1:8880/remote/}}} .
+
+
+== Patternmatcher ==
+
+Message regex matching.
+
+{{{#!highlight python
+class PatternMatcher(Plugin):
+    """Plugin to simplify matching messages based on a regexp."""
+
+    def register_muc(self, callback, pattern):
+    def register_chat(self, callback, pattern):
+    """
+    Register a callback to be called when a message's body matches
+    the pattern (a regex string).
+
+    Callback will be called with the Message object as the argument.
+
+    """
+
+    def register_both(self, callback, pattern):
+    """Equivalent to register_muc(...); register_chat(...)."""
+}}}
+For a usecase, look at the {{{spell}}} plugin, which looks for a {{{(sp?)}}} in a message.
+

=== modified file 'etc/endroid.conf' (properties changed: +x to -x)
=== modified file 'src/endroid.sh'
--- src/endroid.sh	2013-08-08 13:52:15 +0000
+++ src/endroid.sh	2013-08-14 10:10:05 +0000
@@ -1,2 +1,2 @@
 #!/bin/sh
-PYTHONPATH="../lib/wokkel-0.7.1-py2.7.egg":"${PYTHONPATH}" python -m endroid $@
+PYTHONPATH="../lib/wokkel-0.7.1-py2.7.egg":"${PYTHONPATH}":"~/.endroid/plugins/" python -m endroid $@

=== modified file 'src/endroid/confparser.py'
--- src/endroid/confparser.py	2013-08-12 16:07:57 +0000
+++ src/endroid/confparser.py	2013-08-14 10:10:05 +0000
@@ -43,6 +43,9 @@
                 var2
                 var3
         as internal newlines are present
+     - booleans:
+        - literal_eval will convert "True" or "False" to their bool counterparts,
+        but "true", "false", "yes", "no" etc will remain as strings.
     Arguments to .get:
       - 'default' may be specified in which case KeyErrors will never be raised
       - 'return_all' will cause get to return all possible results rather than

=== modified file 'src/endroid/cron.py'
--- src/endroid/cron.py	2013-08-07 16:37:48 +0000
+++ src/endroid/cron.py	2013-08-14 10:10:05 +0000
@@ -45,12 +45,17 @@
 class CronSing(object):
     """
     A singleton providing task scheduling facilities.
-    A function may be registered by calling .register(function, name)
-    and scheduled with either setTimeout(time, name, params) or
-    doAtTime(time, locality, name, params).
+    A function may be registered by calling register(function, name) (returning
+    a Task object).
+    A registered function may be scheduled with either:
+        - setTimeout(time, name, params) / doAtTime(time, locality, name, params)
+        - or by calling either method on the Task object returned
+        by register(), omitting the name parameter.
+    Note that params will be pickled for storage in the database.
+
     When it comes to be called, the function will be called with an argument
-    generated from params (so even if the function needs no arguments it should
-    provide one eg def foo(_) rather than def foo()
+    unpickled from params (so even if the function needs no arguments it should
+    allow for one eg def foo(_) rather than def foo()).
 
     """
     def __init__(self):
@@ -71,9 +76,16 @@
         return float((uss + (ss + ds * 24 * 3600) * 10**6)) / 10**6
 
     def register(self, function, reg_name, persistent=True):
-        """Register the callable fun against reg_name.
-
-        Allows callable to be scheduled with doAtTime or setTimeout."""
+        """
+        Register the callable fun against reg_name.
+
+        Returns a Task object and allows callable to be scheduled with doAtTime
+        or setTimeout either on self, or on the Task object returned.
+
+        If persistent is False, any previous reigstrations against reg_name will
+        be deleted before the new function is registered.
+
+        """
         # reg_name is the key we use to access the function - we can then set the
         # function to be called using setTimeout or doAtTime with regname = name
 

=== modified file 'src/endroid/database.py'
--- src/endroid/database.py	2013-08-06 10:32:33 +0000
+++ src/endroid/database.py	2013-08-14 10:10:05 +0000
@@ -12,9 +12,7 @@
 
 
 class TableRow(dict):
-    """
-    A regular dict, plus a system 'id' attribute.
-    """
+    """A regular dict, plus a system 'id' attribute."""
     __slots__ = ()
 
     def __init__(self, *args, **kwargs):
@@ -27,7 +25,8 @@
         return self[EndroidUniqueID]
 
 class Database(object):
-    """Wrapper round an sqlite3 Database
+    """
+    Wrapper round an sqlite3 Database.
 
     All accesses are synchronous, TODO use twisted.enterprise.adbapi to 
     asynchronise them.
@@ -77,6 +76,11 @@
         return " and ".join(Database._sanitize(c) + "=?" for c in conditions) or "1"
                     
     def create_table(self, name, fields):
+        """
+        Create a new table in the database called 'name' and containing fields 
+        'fields' (an iterable of strings giving field titles).
+
+        """
         if any(f.startswith('_endroid') for f in fields):
             raise ValueError("An attempt was made to create a table with system-reserved column-name (prefix '_endroid').")
         n = Database._sanitize(self._tName(name))
@@ -85,6 +89,7 @@
         Database.raw(query)
     
     def table_exists(self, name):
+        """Check to see if a table called 'name' exists in the database."""
         n = Database._sanitize(self._tName(name))
         query = "SELECT `name` FROM `sqlite_master` WHERE `type`='table' AND `name`={0};".format(n)
         Database.raw(query)
@@ -93,6 +98,13 @@
         return count != 0
     
     def insert(self, name, fields):
+        """
+        Insert a row into table 'name'.
+        
+        Fields is a dictionary mapping field names (as defined in 
+        create_table) to values.
+
+        """
         n = Database._sanitize(self._tName(name))
         query = "INSERT INTO {0} ({1}) VALUES ({2});".format(n,
                                Database._stringFromFieldNames(fields),
@@ -101,6 +113,19 @@
         Database.raw(query, tup)
     
     def fetch(self, name, fields, conditions={}):
+        """
+        Get data from the table 'name'. 
+
+        Returns a list of dictionaries mapping 'fields' to their values, one 
+        dictionary for each row which satisfies a condition in conditions.
+
+        Conditions is a dictionary mapping field names to values. A result
+        will only be returned from a row if its values match those in conditions.
+
+        E.g.: conditions = {'user' : JoeBloggs} 
+        will match only fields in rows which have JoeBloggs in the 'user' field.
+
+        """
         n = Database._sanitize(self._tName(name))
         fields = list(fields) + [EndroidUniqueID]
         query = "SELECT {0} FROM {1} WHERE ({2});".format(
@@ -112,18 +137,26 @@
         return rows
 
     def count(self, name, conditions):
+        """Return the number of rows in table 'name' which satisfy conditions."""
         n = Database._sanitize(self._tName(name))
         query = "SELECT COUNT(*) FROM {0} WHERE ({1});".format(n, Database._buildConditions(conditions))
         r = Database.raw(query, Database._tupleFromFieldValues(conditions)).fetchall()
         return r[0][0]
 
     def delete(self, name, conditions):
+        """Delete rows from table 'name' which satisfy conditions."""
         n = Database._sanitize(self._tName(name))
         query = "DELETE FROM {0} WHERE ({1});".format(n, Database._buildConditions(conditions))
         Database.raw(query, Database._tupleFromFieldValues(conditions))
         return Database.cursor.rowcount
     
     def update(self, name, fields, conditions):
+        """
+        Update rows in table 'name' which satisfy conditions. 
+
+        Fields is a dictionary mapping the field names to their new values.
+
+        """
         n = Database._sanitize(self._tName(name))
         query = "UPDATE {0} SET {1} WHERE ({2});".format(n, Database._buildConditions(fields), Database._buildConditions(conditions))
         tup = Database._tupleFromFieldValues(fields)
@@ -132,11 +165,13 @@
         return Database.cursor.rowcount
     
     def empty_table(self, name):
+        """Remove all rows from table 'name'."""
         n = Database._sanitize(self._tName(name))
         query = "DELETE FROM {0} WHERE 1;".format(n)
         Database.raw(query)
     
     def delete_table(self, name):
+        """Delete table 'name'."""
         n = Database._sanitize(self._tName(name))
         query = "DROP TABLE {0};".format(n)
         Database.raw(query)

=== modified file 'src/endroid/manhole.py'
--- src/endroid/manhole.py	2013-08-06 10:32:33 +0000
+++ src/endroid/manhole.py	2013-08-14 10:10:05 +0000
@@ -19,7 +19,8 @@
 
 # how to log in: ssh user_name@localhost -p port
 def start_manhole(droid, nmspace, cliargs):
-    """Start EnDroid listening for an ssh connection.
+    """
+    Start EnDroid listening for an ssh connection.
 
     Logging in via ssh gives access to a python prompt from which EnDroid's
     internals can be investigated.

=== modified file 'src/endroid/messagehandler.py'
--- src/endroid/messagehandler.py	2013-08-14 10:10:05 +0000
+++ src/endroid/messagehandler.py	2013-08-14 10:10:05 +0000
@@ -137,7 +137,8 @@
         self.do_callback("recv_self", msg, self._unhandled_self_chat)
 
     def send_muc(self, room, body, source=None, priority=PRIORITY_NORMAL):
-        """Send muc message to room.
+        """
+        Send muc message to room.
 
         The message will be run through any registered filters before it is sent.
 
@@ -155,7 +156,8 @@
             logging.info("Filtered out message to {}".format(room))
 
     def send_chat(self, user, body, source=None, priority=PRIORITY_NORMAL):
-        """Send chat message to person with address user.
+        """
+        Send chat message to person with address user.
 
         The message will be run through any registered filters before it is sent.
 

=== modified file 'src/endroid/pluginmanager.py'
--- src/endroid/pluginmanager.py	2013-08-14 10:10:05 +0000
+++ src/endroid/pluginmanager.py	2013-08-14 10:10:05 +0000
@@ -140,7 +140,8 @@
         return self._pm.get(plugin_name)
 
     def get_dependencies(self):
-        """Return an iterable of plugins this plugin depends on.
+        """
+        Return an iterable of plugins this plugin depends on.
 
         This includes indirect dependencies i.e. the dependencies of plugins this
         plugin depends on and so on.
@@ -149,12 +150,13 @@
         return (self.get(dependency) for dependency in self.dependencies)
 
     def get_preferences(self):
-        """Return an iterable of plugins this plugin prefers.
+        """
+        Return an iterable of plugins this plugin prefers.
 
         This includes indirect preferences i.e. the preferences of plugins this
         plugin prefers and so on.
 
-        """        
+        """
         return (self.get(preference) for preference in self.preferences)
 
     def list_plugins(self):

=== modified file 'src/endroid/plugins/ratelimit.py' (properties changed: +x to -x)
=== modified file 'src/endroid/usermanagement.py'
--- src/endroid/usermanagement.py	2013-08-14 10:10:05 +0000
+++ src/endroid/usermanagement.py	2013-08-14 10:10:05 +0000
@@ -22,8 +22,11 @@
 MUC = "muc#roomconfig_"
 
 class Roster(object):
-    """Provides functions for maintaining sets of users registered with and
-    available in a contact list, user group or room"""
+    """
+    Provides functions for maintaining sets of users registered with and
+    available in a contact list, user group or room.
+
+    """
     def __init__(self, name=None, registration_cb=None, deregistration_cb=None):
         self.name = name or "contacts"
 
@@ -199,7 +202,8 @@
     # given a group or room or None (our contact list), return list of users 
     # registered/available there
     def get_users(self, name=None):
-        """Return a set of users registered with 'name'.
+        """
+        Return an iterable of users registered with 'name'.
 
         If name is None, look in contact list.
 
@@ -212,7 +216,8 @@
             return self.room_rosters[name].registered
 
     def get_available_users(self, name=None):
-        """Return a set of users present in 'name'.
+        """
+        Return an iterable of users present in 'name'.
 
         If name is None, look in contact list.
 
@@ -227,7 +232,8 @@
     # given a user or None (us), return list of groups/rooms the user is 
     # registered/available in
     def get_groups(self, user=None):
-        """Return a set of groups 'user' is registered with.
+        """
+        Return an iterable of groups 'user' is registered with.
 
         If user is None, return all registered groups.
 
@@ -235,7 +241,8 @@
         return self._get_user_place(user, self.group_rosters, get_available=False)
 
     def get_available_groups(self, user=None):
-        """Return a set of groups 'user' is present in.
+        """
+        Return an iterable of groups 'user' is present in.
 
         If user is None, return all groups EnDroid is available in.
 
@@ -243,7 +250,8 @@
         return self._get_user_place(user, self.group_rosters, get_available=True)
 
     def get_rooms(self, user=None):
-        """Return a set of rooms 'user' is registered with.
+        """
+        Return an iterable of rooms 'user' is registered with.
 
         If user is None, return all registered rooms.
 
@@ -251,7 +259,8 @@
         return self._get_user_place(user, self.room_rosters, get_available=False)
 
     def get_available_rooms(self, user=None):
-        """Return a set of rooms 'user' is present in.
+        """
+        Return an iterable of rooms 'user' is present in.
 
         If user is None, return all rooms EnDroid is available in.
 
@@ -496,7 +505,8 @@
             return d.addCallback(form_to_string)
 
     def invite(self, user, room, reason=None):
-        """Invite a user to a room.
+        """
+        Invite a user to a room.
 
         Will only send invitation if the user is in our contact list and online,
         and if the user is registered in the room but not currently in it.

=== modified file 'src/endroid/wokkelhandler.py'
--- src/endroid/wokkelhandler.py	2013-08-12 15:10:08 +0000
+++ src/endroid/wokkelhandler.py	2013-08-14 10:10:05 +0000
@@ -137,6 +137,8 @@
         m = Message("muc", sender_jid, message.body, 
                     self.messagehandler, room_userhost)
 
+        # If the jid specified in the config file has a resource,
+        # then we need to reduce it to just the userhost string
         our_jid = self.usermanagement.get_userhost(self.jid)
 
         sender_nick = self.usermanagement.get_nickname(sender_jid, room_userhost)