diff options
Diffstat (limited to 'doc/Manual.txt')
| -rw-r--r-- | doc/Manual.txt | 546 |
1 files changed, 546 insertions, 0 deletions
diff --git a/doc/Manual.txt b/doc/Manual.txt new file mode 100644 index 0000000..0fd4852 --- /dev/null +++ b/doc/Manual.txt @@ -0,0 +1,546 @@ +==================================================== +MeetBot, a supybot plugin for IRC meeting notetaking +==================================================== + + + +Introduction +============ + +MeetBot is a plugin to the IRC bot supybot to facilitate taking of +notes during IRC meetings. This allows you to better communicate with +your project or groups after the IRC meeting, as well as keep the +meeting more under control and on-topic. + +This manual is for user and meeting chair reference. For installation +support, see ``README.txt``. + + + + +Tutorial +======== + +Let's go through, step by step, how a typical meeting might run:: + + < MrBeige> #startmeeting + +We use the ``#startmeeting`` command to tell MeetBot to start the +meeting. The person who calls the command becomes the chair - having +the power to guide the meeting. However, by default MeetBot allows +other participants to enter most things into the logs, since inviting +contributions is generally a good thing.:: + + < MeetBot> Meeting started Wed Jun 17 05:00:49 2009 UTC. The chair + is MrBeige. + < MeetBot> Information about MeetBot at + http://wiki.debian.org/MeetBot , Useful Commands: #action + #agreed #halp #info #idea #link #topic. + +MeetBot gives us a little bit of information about the meeting.:: + + < MrBeige> #topic should we release or not? + -!- MeetBot changed the topic of #meetbot-test to: should we release + or not? + +We use the ``#topic`` command to tell MeetBot to move to the first +topic. MeetBot sets the topic in the channel to the topic which is +given on the line. Don't worry, the topic will be restored at the end +of the meeting.:: + + < MrBeige> #info we have two major blocking bugs: the character set + conversion, and the segfaults heisenbug in the save + routine. + +When there is important things said, we don't want them to be lost in +the irclogs. Thus, we use the ``#info`` command to make a note of +it in the meeting minutes. It is also highlighted in the irclogs +which MeetBot takes.:: + + < MrBeige> #agreed we give one week to fix these (no other changes + accepted), and then release + +We also have the ``#agreed`` command to use. This can only be used by +the chairs of the meeting, and should (obviously) be used to document +agreement. The rest of the line goes into the minutes as the thing +agreed on.:: + + < MrBeige> #action MrGreen and MrMauve work together to fix the bugs + < MrBeige> #action MrBeige releases when done + +We have the ``#action`` command. This one is works just like the last +two, but has one extra feature: at the end of the meeting, it makes a +list of "Action Items", useful for being sure things get taken care +of. But there is more: it also makes a list of action items sorted by +*nick*. This can be used to easily see what is assigned to you. In +order for an item to be sorted by a nick, that nick has got to say +something during the meeting (but also see the ``#nick`` command), and +you have to use their nick exactly (use tab completion!).:: + + < MrBeige> #topic goals for release after next + -!- MeetBot changed the topic of #meetbot-test to: goals for release + after next + +Moving on to the next topic...:: + + ... + < MrBeige> #info make it better + ... + < MrBeige> #info release faster + ... + +Record some of the important items from this section.:: + + < MrBeige> #endmeeting + +Hit the ``#endmeeting`` command. The meeting ends, and logs and +minutes are saved:: + + -!- MeetBot changed the topic of #meetbot-test to: General + discussion of MeetBot + < MeetBot> Meeting ended Wed Jun 17 05:03:45 2009 UTC. Information + about MeetBot at http://wiki.debian.org/MeetBot . + < MeetBot> Minutes: http://rkd.zgib.net/meetbot/meetbot-test/meetbot-test.html + < MeetBot> Log: http://rkd.zgib.net/meetbot/meetbot-test/meetbot-test.log.html + +MeetBot conveniently tells us where all of the logs are stored. You +can look at the `logs`_ and `minutes`_ online. + +.. _logs: http://rkd +.. _minutes: http://rkd + + + + +Commands +======== + +All commands are case-insensitive, and use the ``#`` prefix +character. Not all commands have output. This might be confusing, +because you don't know if it's been acted on or not. However, this is +a conscious design decision to try to keep out of the way and not +distract from the real people. If something goes wrong, you can +adjust and have MeetBot re-process the logs later. + +#startmeeting + Starts a meeting. The calling nick becomes the chair. If any text + is given on the rest of the line, this becomes the meeting topic, + see ``#meetingtopic`` above. + +#endmeeting + End a meeting, save logs, restore previous topic, give links to + logs. You know the drill. (Chairs only.) + +#topic + Set the current topic of discussion. MeetBot changes the topic in + the channel (saving the original topic to be restored at the end of + the meeting). (Chairs only.) + +#agreed (alias #agree) + Mark something as agreed on. The rest of the line is the details. + (Chairs only.) + +#chair and #unchair + Add new chairs to the meeting. The rest of the line is a list of + nicks, separated by commas and/or spaces. The nick which started + the meeting is the ``owner`` and can't be de-chaired. The command + replies with a list of the current chairs, for verification (Chairs + only.) Example:: + + < MrBeige> #chair MrGreen MsAlizarin + < MeetBot> Current chairs are: MsAlizarin MrBeige MrGreen + +#action + + Add an ``ACTION`` item to the minutes. Provide irc nicks of people + involved, and will be both a complete listing of action items, and a + listing of action items sorted by nick at the end of the meeting. + This is very useful for making sure this gets done. Example:: + + < MrBeige> #action MrGreen will read the entire Internet to + determine why the hive cluster is under attack. + + If MrGreen has said something during the meeting, this will be + automatically assigned to him. + +#info + Add an ``INFO`` item to the minutes. Example:: + + < MrBeige> #info We need to spawn more overlords before the next + release. + +#link + Add a link to the minutes. The URL must be the first thing on the + line, separated by a space from the rest of the line, and it will be + properly hyperlinked. This command is automatically detected if the line + starts with http:, https:, mailto:, and some other common protocols + defined in the ``UrlProtocols`` configuration variable. Examples:: + + < MrBeige> #link http://wiki.debian.org/MeetBot/ is the main page + < MrBeige> http://wiki.debian.org/MeetBot/ is the main page + + Both of these two examples are equivalent, and will hyperlink + properly. The first example below won't hyperlink properly, the + second one won't be automatically detected:: + + < MrBeige> #link the main page is http://wiki.debian.org/MeetBot/ + < MrBeige> the main page is http://wiki.debian.org/MeetBot/ + + + + +Less-used Commands +================== + +#meetingtopic + Sets the "meeting topic". This will always appear in the topic in + the channel, even as the #topic changes. The format of the IRCtopic + is "<topic> (Meeting Topic: <meeting topic>)". (Chairs only.) + +#commands + List recognized supybot commands. This is the actual "help" command. + +#idea + Add an ``IDEA`` to the minutes. + +#help (alias #halp) + Add a ``HELP`` item to the minutes. Confusingly, this does *not* give + supybot help. See #commands. + +#accepted (alias #accept) + Mark something as accepted. The rest of the line is the details. + (Chairs only.) + +#rejected (alias #reject) + Mark something as rejected. The rest of the line is the details. + (Chairs only.) + +#save + Write out the logs right now. (Chairs only.) + +#nick + Make a nick be recognized by supybot, even though it hasn't said + anything. This is only useful in order to make a list of action + items be grouped by this nick at the end of the meeting. + +#undo + Remove the last item from the meeting minutes. Only applies to + commands which appear in the final output. + +#restrictlogs + When logs are saved, remove the permissions specified in the + configuration variable ``RestrictPerm``. (Chairs only.) + +#lurk and #unlurk + When ``lurk`` is set, MeetBot will only passively listen and take + notes (and save the notes), not reply or change the topic This is + useful for when you don't want disruptions during the meeting. + (Chairs only.) + +#meetingname + Provide a friendly name which can be used as a variable in the + filename patterns. For example, you can set + filenamePattern = '%(channel)s/%%Y/%(meetingname)s.%%F-%%H.%%M' + to allow #meetingname to categorize multiple types of meeting + occurring in one channel. + + All spaces are removed from the rest of the line and the string is + converted to lowercase. If ``meetingname`` is not provided, it + defaults to ``channel``. (Chairs only.) + + + +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> ...``). + +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. + + + +Hints on how to run an effective meeting +======================================== + +*Please contribute to this section!* + + * Have an agenda. Think about the agenda beforehand, so that + attendees are not tempted to jump ahead and discuss future items. + This will make it very hard to follow. + * *Liberally* use the ``#action`` command, making sure to include the + nick of the person responsible. It will produce an easy-to-scan + list of things to do, as well as a sorted-by-nick version. This + will make these things more likely to get done. + * In the same spirit, liberally use ``#info`` on important pieces of + data. If you think you'll want to refer to it again, ``#info`` + it. Assigning someone to watch the meeting to ``#info`` other + people's lines (if they forget) usually pays off. + * Don't be afraid to tell attendees to wait for a future topic to + discuss something. + * Delegate where possible and have those interested discuss the + details after the meeting, where applicable. No need to take + everyone's time if not everyone needs to decide. (This only + applies to some types of meetings) + * Sometimes one chair to manage the topic at hand, and one chair to + manage all people who are going off-topic, can help. + + + + +Configuration +============= + +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. + +Here is a minimal usage example. You need at *least* this much to +make it run. Put this in ``meetingLocalConfig.py`` before you first +start supybot:: + + Class Config(object): + # These two are **required**: + logFileDir = '/home/richard/meetbot/' + logUrlPrefix = 'http://rkd.zgib.net/meetbot/' + +Two other more commonly used options are:: + + filenamePattern = '%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M' + MeetBotInfoURL = 'http://some_other_side.tld' + +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. + +To reload a configuration in a running supybot, you can just reload +the plugin in supybot --- the module is reloaded. Specifically, +``/msg YourBotName reload MeetBot``. + + + +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 +``supybot.plugins.MeetBot.enableSupybotBasedConfig`` variable must be +set to True. Then the MeetBot plugin must be reloaded:: + + /msg YourBot config supybot.plugins.MeetBot.enableSupybotBasedConfig True + /msg YourBot reload MeetBot + +Now you can list the values available for configuration (the list +below may not be up to date):: + + /msg YourBot config list supybot.plugins.MeetBot + ----> #endMeetingMessage, #filenamePattern, #input_codec, + #logFileDir, #logUrlPrefix, #MeetBotInfoURL, #output_codec, + #pygmentizeStyle, #specialChannelFilenamePattern, + #startMeetingMessage, #timeZone, #usefulCommands, + enableSupybotBasedConfig, and public + +Setting a value for a variable:: + + /msg YourBot config supybot.plugins.MeetBot.logUrlPrefix ... + ... http://meetings.yoursite.net/ + + +At present, not all variables are exported to supybot. All string +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. + +If you want to disable supybot-based config for security reasons, set +``dontBotConfig`` to True in your custom configuration class in +``meetingLocalConfig.py``. + + + +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. + +``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. + +``filenamePattern`` + This defaults to ``'%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M'``, + and is the pattern used for replacements to identify the name of + the file basename (including possible sub-directories) in which to + store the meeting output files. This is the suffix to + ``logFileDir`` and ``logUrlPrefix``. + + Variables available for replacement using ``%(name)s`` include: + ``channel``, ``meetingname``. Double percent signs (e.g.: ``%%Y`` + are time formats, from ``time.strftime``. + + 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``) + +``MeetBotInfoURL`` + This is a URL given in beginning and ending messages and minutes + files as a "go here for more information" link. + + + +Other Config Variables +---------------------- + +These variables are set either in ``meetingLocalConfig.py`` (in the +``Config`` class) or in the supybot registry. + +``RestrictPerm`` + An int listing which permissions to remove when using the + ``#restrictlogs`` command. It is best to use the python ``stat`` + module to set it:: + + RestrictPerm = stat.S_IRWXO|stat.S_IRWXG + +``specialChannels`` and ``specialChannelFilenamePattern`` + When you are doing MeetBot testing, you would rather not have + nonstop different filenames each time you do a test meeting. + If a channel is in ``specialChannels``, it will use + ``specialChannelFilenamePattern`` instead of ``filenamePattern`` + when storing logs. ``specialChannels`` is a tuple listing channel + names. Example: the defaults are ``("#meetbot-test", + "#meetbot-test2")`` and ``'%(channel)s/%(channel)s'`` (note that + there is no time-dependence in the name). + +``UrlProtocols`` + Tuple of protocols to use to automatically detect link. Example: + the default tuple is ``('http:', 'https:', 'irc:', 'ftp:', + 'mailto:', 'ssh:')``. + +``command_RE`` + How commands are detected. See code. + +``pygmentizeStyle`` + Style for the Pygments module to use to colorize the IRC logs. + The default is ``"friendly"``. + +``timeZone`` + Timezone used in the bot. Note: This will not yet work on a + per-channel basis. The default is ``"UTC"`` + +``startMeetingMessage`` + +``endMeetingMessage`` + Message printed at the beginning/end of the meetings. Some + ``%(name)s`` replacements are available: ``chair``, ``starttime``, + ``timeZone``, ``endtime``, ``MeetBotInfoURL``, ``urlBasename``. + +``input_codec`` + +``output_codec`` + 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(), + } + + + +Advanced Configuration +---------------------- + +This gives a few examples of things you can do via +``meetingLocalConfig.py``. Most people probably won't need these +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': + self.logFileDir = '/some/directory' + else: + self.logFileDir = '/some/other/directory' + + +The display styles (in html writers) can be modified also, by using +the starthtml and endhtml attributes (put this in +meetingLocalConfig.py:: + + import items + items.Agreed.starthtml = '<font color="red">' + 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:: + + class Config(object): + def init(self): + def do_party(self, nick, time_, **kwargs): + self.reply("We're having a party in this code!") + self.reply(("Owner, Chairs: %s %s"%( + self.owner,sorted(self.chairs.keys())))) + self.M.do_party = types.MethodType( + do_party, self.M, self.M.__class__) + + +Make a command alias. Make ``#weagree`` an alias for ``#agreed``:: + + class Config(object): + def init(self): + self.M.do_weagree = self.M.do_agreed + + +Help and Support +================ + +The channel ``#meetbot`` on irc.oftc.net is the best place to go. |