Many manual updates

- Reorganize Administratiors section.
- Explain the meeting.py / supybot divide.
- Document writer_map config variable and all writers.
- Document replay functionality.
- Fix other random errors.

darcs-hash:20090919190015-82ea9-f6ad04b2311ea0dfe4737311b58b524e8485a37a.gz

1 files changed, 248 insertions, 78 deletions

diff --git a/doc/Manual.txt b/doc/Manual.txt
index 5764a89..de6f1e2 100644
--- a/doc/Manual.txt
+++ b/doc/Manual.txt
@@ -284,61 +284,55 @@ Administrators
 Overview
 --------
 
+Unfortunately, MeetBot seems a bit complex to configure.  In order to
+keep things straight, keep this in mind: MeetBot has two distinct
+pieces.  The first (``meeting.py`` and friends) is the meeting parser
+and note/logfile generator.  This part can run independently,
+*without* the supybot plugin.  The second part interfaces the core
+``meeting.py`` to supybot, to make it usable via IRC.
 
+When reading about how to run MeetBot, keep this in mind, and if
+something is applicable to ``meeting.py`` features, just supybot
+features, or both.
 
+This design split greatly increases modularity (a "good thing"), and
+also allows the Replay functionality.  It should also allow other bot
+plugins to easily be written.
 
 
-Supybot admin commands
-----------------------
 
-These commands are for the bot owners to manage all meetings served by
-their bot.  The expected use of these commands is when the bot is on
-many channels as a public service, and the bot owner sometimes needs
-to be able to monitor and adjust the overall situation, even if she is
-not the chair of a meeting.
 
-All of these are regular supybot commands (as opposed to the commands
-above).  That means that the supybot capability system applies, and
-they can be given either in any channel, either by direct address
-(``BotName: <command> <args> ...``) or with the bot prefix character
-(e.g. ``@<commandname> <args> ...``).  If there are commands with the
-same name in multiple plugins, you need to prefix the command with the
-plugin name (for example, ``BotName: meetbot recent`` instead of
-``BotName: recent``)
+Replay functionality
+--------------------
 
-These are restricted to anyone with the ``admin`` capability on the
-bot.
+Let's say you had a meeting which happened a while ago, and you would
+like to update the logs to a newer format.  If supybot was the only
+way to use MeetBot, you'd be out of luck.  Luckily, there is an
+independent way to replay meetings::
 
-``listmeetings``
-  List all meetings.
+    python /path/to/meeting.py replay /path/to/old_meeting.log.txt
 
-``savemeetings``
-  Saves all active meetings on all channels and all networks.
+You run the meeting.py file as a script, giving the subcommand
+``replay`` and then a path to a ``.log.txt`` file from a previous
+meeting (or from some other source of IRC logs, it's essentially the
+irssi/xchat format).  It parses it and processes the meeting, and
+outputs all of the usual ``.html``, ``.log.html``, and so on files in
+the directory parallel to the input file.
 
-``addchair <channel> <network> <nick>``
-  Forcibly adds this nick as a chair on the giver channel on the given
-  network, if a meeting is active there.
+This is useful if you want to upgrade your output formats, MeetBot
+broke and you lost the realtime log and want to generate a summary
+using your own logfiles, remove or change something in the logs that
+was incorrect during the meeting.  As such, this is an important
+feature of MeetBot.
 
-``deletemeeting <channel> <network> <saveit=True>``
-  Delete a meeting from the cache.  If save is given, save the meeting
-  first.  The default value of ``save`` is True.  This is useful for
-  when MeetBot becomes broken and is unable to properly save a
-  meeting, rendering the ``#endmeeting`` command non-functional.
-
-``recent``
-  Display the last ten or so started meetings, along with their
-  channels.  This is useful if you are the bot admin and want to see
-  just who all is using your bot, for example to better communicate
-  with those channels.
-
-To connect to multiple IRC networks, use the supybot ``Network``
-plugin to manage them.  First, load the ``Network`` plugin, then use
-the ``connect`` command to connect to the other network.  Finally, you
-need to tell supybot to join channels on the new.  To do
-that, you can use ``network command <other_network> join <channel>``.
-(Alternatively, you can /msg the bot through the other network, but
-you'll have to register your nick to it on the other network in order
-for it to accept commands from you.)
+However, this does make configuration changes harder.  Since the
+replay function works *independent* of supybot, any configuration that
+is done in supybot will be invisible to the replay function.  Thus, we
+have to have a non-supybot mechanism of configuring MeetBot.  There
+was a supybot way of configuring MeetBot added later, which can adjust
+most variables.  However, if something is configured here, it won't be
+seen if a file is replayed.  This might be OK, or it might not be,
+depending on the variable.
 
 
 
@@ -346,6 +340,13 @@ for it to accept commands from you.)
 Configuration
 -------------
 
+meetingLocalConfig.py configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the non-supybot method of configuration, and allows the most
+flexibility.  **It works for configuring supybot, too**, but requires
+shell access and a MeetBot reload to change.
+
 Configuration is done by creating a file ``meetingLocalConfig.py`` in
 the plugin directory, or somewhere in your PYTHONPATH.  It works by
 (automatically, not user-visible) subclassing the Config class.
@@ -367,10 +368,12 @@ Two other more commonly used options are::
 Place all of the configuration variables inside of the class
 body like this.
 
-``meetingLocalConfig.py`` is a complete execution, and causes a
-subclass of the main Config object.  Thus, you can do some advanced
-(or just crazy) things like add a new meeting command, meeting
-agenda item type, or more.  Not all of these are documented here.
+``meetingLocalConfig.py`` is imported via python, so all the usual
+benefits and caveats of that apply.  It causes a subclass of the main
+Config object.  Thus, you can do some advanced (or just crazy) things
+like add a new meeting command, meeting agenda item type, or more.
+Some of these ideas are documented under the "Advanced configuration"
+section below.
 
 To reload a configuration in a running supybot, you can just reload
 the plugin in supybot --- the module is reloaded.  Specifically,
@@ -381,10 +384,15 @@ the plugin in supybot --- the module is reloaded.  Specifically,
 Supybot-based config
 ~~~~~~~~~~~~~~~~~~~~
 
-In addition to the normal ``meetingLocalConfig.py`` based
-configuration, there is a mode where the supybot registry system can
-be used to set the values of some configuration variables.  To enable
-this system, first the
+This is the system that configures MeetBot based on the supybot
+registry system.  Thus, it can be adjusted by anyone with the proper
+supybot capabilities.  However, the configuration in the supybot
+registry *won't* be used if the ``replay`` functionality is used (see
+above).  Thus, for example, if you configure the MediaWiki writer
+using ``supybot.plugins.MeetBot.writer_map``, and then ``replay`` the
+meeting, the MediaWiki output will *not* be updated.
+
+To enable this system, first the
 ``supybot.plugins.MeetBot.enableSupybotBasedConfig`` variable must be
 set to True.  Then the MeetBot plugin must be reloaded::
 
@@ -405,11 +413,15 @@ Setting a value for a variable::
 
     /msg YourBot config supybot.plugins.MeetBot.logUrlPrefix http://meetings.yoursite.net/
 
+Most variables (those with # prepended) can be set on a per-channel
+basis (they are set up as channel-specific variables).
+
 
 At present, not all variables are exported to supybot.  All string and
 boolean variables are, as well certain other variables for which a
-wrapper has been written.  If a variable doesn't appear in the supybot
-registry, it can't be set via the registry.
+wrapper has been written (``writer_map`` in particular).  If a
+variable doesn't appear in the supybot registry, it can't be set via
+the registry.
 
 If you want to disable supybot-based config for security reasons, set
 ``dontBotConfig`` to True in your custom configuration class in
@@ -418,19 +430,19 @@ If you want to disable supybot-based config for security reasons, set
 
 
 Required or important configuration
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These variables are set either in ``meetingLocalConfig.py`` (in the
 ``Config`` class) or in the supybot registry.
 
 ``logFileDir``
-    The filesystem directory in which the meeting outputs are stored.
-    **Required** or supybot can't save properly.
+    The filesystem directory in which the meeting outputs are stored,
+    defaulting to ".".  **Required**.
 
 ``logUrlPrefix``
     The URL corresponding to ``logFileDir``.  This is prepended to
     filenames when giving end-of-meeting links in the channel.
-    **Required** or supybot's URLs will be wrong.
+    **Required** or supybot's URLs will be missing.
 
 ``filenamePattern``
     This defaults to ``'%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M'``,
@@ -446,19 +458,119 @@ These variables are set either in ``meetingLocalConfig.py`` (in the
     This filename does *not* include extensions.  Those are found from
     the writers, via the variable ``writer_map``.
 
-    Putting these all together, a set of variables could be:
-      1) ``logFileDir  =  /srv/www/meetings/``
-      2) ``%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M``
-      3) (extensions come from ``writers_map``)
+Putting these all together, a set of variables could be:
+  1) ``logFileDir  =  /srv/www/meetings/``
+  2) ``%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M``
+  3) (``.html``, ``.txt``, etc, extensions come from ``writers_map``)
 
 ``MeetBotInfoURL``
     This is a URL given in beginning and ending messages and minutes
     files as a "go here for more information" link.
 
 
+writer_map configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``writer_map`` tells how we want to output the results of the meeting.
+It is, as you can guess, a mapping from filename extensions
+(``.html``, ``.log.html``, ...) to what we want to output to that file
+(``writers.HTML``, ``writers.HTMLlog``, ...)
+
+Using ``meetingLocalConfig.py``, it is python dictionary listing what
+output formats will be used to write our final results to a file,
+along with extensions to use.  For example, in
+``meetingLocalConfig.py``::
+
+    import writers
+
+    class Config:
+        writer_map = {
+            '.log.html':writers.HTMLlog,
+            '.html': writers.HTML,
+            '.txt': writers.RST,
+            '.mw':writers.MediaWiki,
+            }
+
+
+This *can* be configured through supybot.  To do this, set
+``supybot.plugins.MeetBot.writer_map`` to a space-separated list of
+``WriterName:.extension`` pairs (note the different ordering from the
+python dictionary).  For example, to list the current setting (in
+private message with the bot)::
+
+    <MrBeige> config plugins.MeetBot.writer_map
+    <MeetBot> HTML2:.html MediaWiki:.mw HTMLlog2:.log.html Text:.txt
+
+And to set it (again, in private message with the bot)::
+
+    <MrBeige> config plugins.MeetBot.writer_map HTML2:.html MediaWiki:.mw HTMLlog2:.log.html Text:.txt
+
+
+
+
+The available writers are (with default extensions, if enabled by
+default):
+
+``TextLog`` (``.log.txt``)
+    Plain-text logs suitable for replaying.  This does **not** have to
+    be explicitly enabled listed-- it is automatically enabled
+    whenever it is needed (currently, only when a meeting comes
+    realtime from supybot, not when being replayed)
+
+``HTMLlog`` (``.log.html``)
+    Alias for the current default HTML-pretty logs output format,
+    currently ``HTMLlog2``.
+
+``HTMLlog2``
+    Writes the logs in a HTML-pretty, CSS-customizable way (see section
+    below).
+
+``HTML`` (``.html``)
+    Alias for the current default HTML output format for the meeting
+    notes, currently ``HTML2``.
+
+``HTML2``
+    Meeting notes, in a numbered list HTML output format.
+    Configurable via CSS (see section below).
+
+``Text`` (``.txt``)
+    A meeting notes format, as a plain text file
+
+``MediaWiki``
+    MediaWiki output.  This doesn't upload *to* a MediaWiki instance,
+    but that could be added later.
+
+``PmWiki``
+    PmWiki output.  This doesn't upload *to* a PmWiki instance,
+    but that could be added later.
+
+Obsolete writers are:
+
+``HTMLlog1``
+    Old HTML writer.  This one requires the Python module ``pygments``
+    to be installed.  HTMLlog2 was written to remove this dependency.
+    HTMLlog2 is just as pretty as this is, and HTMLlog2 is
+    configurable via CSS.
+
+``HTML1``
+    Old, table-based HTML writer.
+
+``ReST``
+    ReStructured Text output.  Since ReStructured Text is a bit strict
+    in it's parser, user input from the IRC meeting will often mess up
+    the conversion, and thus this isn't recommended for true use until
+    better escape functions can be written.  (There is no security
+    risk from this plugin, ReST is run in secure mode).
+
+``HTMLfromReST``
+    This runs the ReStructured Text writer, and uses ``docutils`` to
+    convert it to HTML.  This requires the ``docutils`` package of
+    Python to be installed.
+
+
 
 Other config variables
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 These variables are set either in ``meetingLocalConfig.py`` (in the
 ``Config`` class) or in the supybot registry.
@@ -517,16 +629,7 @@ These variables are set either in ``meetingLocalConfig.py`` (in the
     Input and output character set encodings.
 
 ``writer_map``
-    A python dictionary listing what output formats will be used to
-    write our final results to a file, along with extensions to use.
-    For example::
-
-        writer_map = {
-            '.log.html':writers.HTMLlog(),
-            '.html': writers.HTML(),
-            '.txt': writers.RST(),
-            #'.rst.html':writers.HTMLfromRST(),
-            }
+    See the description in the section above.
 
 ``cssFile_minutes`` and ``cssFile_log``
 
@@ -553,7 +656,7 @@ These variables are set either in ``meetingLocalConfig.py`` (in the
 
 
 Advanced configuration
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 This gives a few examples of things you can do via
 ``meetingLocalConfig.py``.  Most people probably won't need these
@@ -562,12 +665,22 @@ things, and they aren't thoroughly explained here.
 You can make a per-channel config::
 
     class Config(object):
-        def init(self):
-	    if self.M.channel == '#some-channel':
+        def init_hook(self):
+            if self.M.channel == '#some-channel':
                 self.logFileDir = '/some/directory'
             else:
                 self.logFileDir = '/some/other/directory'
 
+Make a per-channel writer_map (note that you shouldn't change
+writer_map in place)::
+
+    import writers
+    class Config(object):
+        def init_hook(self):
+            if self.M.channel == '#some-channel':
+                self.writer_map = self.writer_map.copy()
+                self.writer_map['.mw'] = writers.MediaWiki
+
 
 The display styles (in html writers) can be modified also, by using
 the starthtml and endhtml attributes (put this in
@@ -578,9 +691,11 @@ meetingLocalConfig.py::
     items.Agreed.endhtml = '</font>'
 
 
-Adding a new custom command via ``meetingLocalConfig.py``.  This
-likely won't make sense unless you examine the code a bit::
+Adding a new custom command via ``meetingLocalConfig.py``.  (This
+likely won't make sense unless you examine the code a bit and know
+esoteric things about python method types)::
 
+    import types
     class Config(object):
         def init(self):
             def do_party(self, nick, time_, **kwargs):
@@ -600,6 +715,61 @@ Make a command alias.  Make ``#weagree`` an alias for ``#agreed``::
 
 
 
+Supybot admin commands
+----------------------
+
+These commands are for the bot owners to manage all meetings served by
+their bot.  The expected use of these commands is when the bot is on
+many channels as a public service, and the bot owner sometimes needs
+to be able to monitor and adjust the overall situation, even if she is
+not the chair of a meeting.
+
+All of these are regular supybot commands (as opposed to the commands
+above).  That means that the supybot capability system applies, and
+they can be given either in any channel, either by direct address
+(``BotName: <command> <args> ...``) or with the bot prefix character
+(e.g. ``@<commandname> <args> ...``).  If there are commands with the
+same name in multiple plugins, you need to prefix the command with the
+plugin name (for example, ``BotName: meetbot recent`` instead of
+``BotName: recent``)
+
+These are restricted to anyone with the ``admin`` capability on the
+bot.
+
+``listmeetings``
+  List all meetings.
+
+``savemeetings``
+  Saves all active meetings on all channels and all networks.
+
+``addchair <channel> <network> <nick>``
+  Forcibly adds this nick as a chair on the giver channel on the given
+  network, if a meeting is active there.
+
+``deletemeeting <channel> <network> <saveit=True>``
+  Delete a meeting from the cache.  If save is given, save the meeting
+  first.  The default value of ``save`` is True.  This is useful for
+  when MeetBot becomes broken and is unable to properly save a
+  meeting, rendering the ``#endmeeting`` command non-functional.
+
+``recent``
+  Display the last ten or so started meetings, along with their
+  channels.  This is useful if you are the bot admin and want to see
+  just who all is using your bot, for example to better communicate
+  with those channels.
+
+To connect to multiple IRC networks, use the supybot ``Network``
+plugin to manage them.  First, load the ``Network`` plugin, then use
+the ``connect`` command to connect to the other network.  Finally, you
+need to tell supybot to join channels on the new.  To do
+that, you can use ``network command <other_network> join <channel>``.
+(Alternatively, you can /msg the bot through the other network, but
+you'll have to register your nick to it on the other network in order
+for it to accept commands from you.)
+
+
+
+
 Developers
 ==========