Merge lp:~stefanor/ibid/manpages-510020 into lp:~ibid-core/ibid/old-trunk-1.6

[Stefano Rivera]

[lp:~stefanor/ibid/manpages-510020]

875. By Stefano Rivera on 2010-01-22

Rename ibid-pub-client in setup.py

[Jonathan Hitchcock (vhata)]

All seems good.

I would change the description to "multi-protocol, easily extensible bot written in python" and not use it so much in the actual manpages themselves (it becomes a $phrase that sounds silly).

Also, the knab import script should reference knab.

Otherwise, seems fine - we really just need to get this stuff in...

review: Approve

[lp:~stefanor/ibid/manpages-510020]

876. By Stefano Rivera on 2010-01-23

See also Knab's URL for knab-import

877. By Stefano Rivera on 2010-01-23

Reword Ibid description

878. By Stefano Rivera on 2010-01-24

e.g., not i.e.

879. By Stefano Rivera on 2010-01-24

Typos, spotted by Max

[Max Rabkin (max-rabkin)]

review: Approve

[marcog (marco-gallotta)]

Most comments here are pedantic, so ignore them if you feel like it. :)

> There should there be an existing ibid.ini in the current directory, or one should be
> provided on the command line.

Can ibid.ini not be located in /etc ?

> Note that you should use twistd(1) where possible instead of calling this directly,
> as certain classes of error (problems in twisted callbacks) will go unnoticed in this
> program. That has no harmful effects, but the developers may miss out on some good
> bug reports.

Should this really be under "BUGS"?

How about adding that this can be achieved by running "twistd -n ibid"?

> SEE ALSO
> ibid(1), ibid.ini(5), ibid-setup(1), http://ibid.omnia.za.net/

This is in ibid.1. Should it really be referencing what I believe is itself?

> A complete description of the contents of this file is out of the scope of this man‐
> page, for more details see the Ibid documentation.

Break up into 2 sentences.

> This file will be written to by the bot when configuration settings are altered
> online. It can also be edited manually and a running bot told to "reload config".

Maybe mention that when automatically written to, the bot will preserve manual edits.

Weren't there some bugs associated with "reload config" not fully working? Perhaps mention them under a BUGS section.

> Settings related to permissions and authentication. Permissions listed in auth.per‐
> missions are granted to all users unless revoked by source or account.

I don't like how tha man page splits auth.permissions over multiple lines. Is there a way to force it to keep it on a single line?

> Plugin configuration, each plugin is configured within a section named after the plu‐
> gin.

I don't like that comma. Maybe a colon? There are also other places where this occurs.

> SEE ALSO
> ibid(1), ibid-objgraph(1), http://ibid.omnia.za.net/

This is in ibid-objgraph.1. I guess that ibid-objgraph(1) should have been ibid-memgraph(1)

> This utility is passing events to a running Ibid bot, or executing RPC-exposed func‐
> tions remotely.

This utility is *for* passing

> ibid-plugin.1 BUGS

It also doesn't emulate accounts/identities.

> ibid-setup - Create a configuration file and Database for an Ibid bot

Create a *basic* configuration file and *d*atabase as a starting point for an Ibid bot

> This program installs a new Ibid bot.

Does it really *install* the bot? When I read install, I think it does more than what this script does. Maybe "configures"?

review: Needs Fixing

[Stefano Rivera (stefanor)]

> Can ibid.ini not be located in /etc ?

If you have a single machine-wide Ibid, yes it can. However that's more of a packaging question. At the moment, we aren't doing anything about that kind of thing.
See http://svn.debian.org/viewsvn/python-apps/packages/ibid/trunk/debian/README.Debian?view=markup

> Should this really be under "BUGS"?

Well, it is a bug that it misses those massages, yes. I could rephrase it to say that. r880

> How about adding that this can be achieved by running "twistd -n ibid"?

Yeah. r880

> > ibid(1), ibid.ini(5), ibid-setup(1), http://ibid.omnia.za.net/
> This is in ibid.1. Should it really be referencing what I believe is itself?

Correct. r881

> > A complete description of the contents of this file is out of the scope of
> > this man‐page, for more details see the Ibid documentation.
> Break up into 2 sentences.

Done. r882

> Maybe mention that when automatically written to, the bot will preserve manual
> edits.

r883

> Weren't there some bugs associated with "reload config" not fully working?
> Perhaps mention them under a BUGS section.

No, I think they were fixed.

> I don't like how tha man page splits auth.permissions over multiple lines. Is
> there a way to force it to keep it on a single line?

Yes, one can tell it not to hyphenate specific words. File a bug for 0.2, if you want ot do that to all of them :)

> > Plugin configuration, each plugin is configured within a section named after
> I don't like that comma. Maybe a colon? There are also other places where this
> occurs.

r884

> > SEE ALSO
> > ibid(1), ibid-objgraph(1), http://ibid.omnia.za.net/
> This is in ibid-objgraph.1. I guess that ibid-objgraph(1) should have been
> ibid-memgraph(1)

r885

> > This utility is passing events to a running Ibid bot, or executing RPC-
> exposed functions remotely.
> This utility is *for* passing

r886

> > ibid-plugin.1 BUGS
> It also doesn't emulate accounts/identities.

Well spotted. r887

> > ibid-setup - Create a configuration file and Database for an Ibid bot
> Create a *basic* configuration file and *d*atabase as a starting point for an
> Ibid bot

Not mad about "starting point". r888

> > This program installs a new Ibid bot.
> Does it really *install* the bot? When I read install, I think it does more
> than what this script does. Maybe "configures"?

r889

[lp:~stefanor/ibid/manpages-510020]

880. By Stefano Rivera on 2010-01-24

Rework the BUGS in ibid.1

881. By Stefano Rivera on 2010-01-24

ibid.1 refers to itself, it should rather refer to ibid-setup.1

882. By Stefano Rivera on 2010-01-24

Break up first section of ibid.ini.5 and link to Ibid documentation

883. By Stefano Rivera on 2010-01-24

Explain config file writing in relation to comments

884. By Stefano Rivera on 2010-01-24

s/,/./

885. By Stefano Rivera on 2010-01-24

Refer to ibid-memgraph from ibid-objgraph, not itself

886. By Stefano Rivera on 2010-01-24

Missing 'for' in ibid-pb-client.1

887. By Stefano Rivera on 2010-01-24

ibid-plugin grants user all permissions

888. By Stefano Rivera on 2010-01-24

Clarify one-liner for ibid-setup

889. By Stefano Rivera on 2010-01-24

Don't say ibid-setup installs

[marcog (marco-gallotta)]

Looks good

review: Approve

=== added directory 'man'
=== added file 'man/ibid-db.1'
--- man/ibid-db.1	1970-01-01 00:00:00 +0000
+++ man/ibid-db.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,59 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-DB "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-db \- Database management utility for Ibid
+.SH SYNOPSIS
+.B ibid-db command
+.RI [ options ...]
+.SH DESCRIPTION
+This utility is for offline management of your Ibid bot's database.
+Used for import, export, and upgrades.
+.P
+The export format is DBMS-agnostic and can be used to migrate between different
+databases.
+.SH COMMANDS
+.TP
+\fB\-e\fR \fIFILE\fR, \fB\-\-export\fR=\fIFILE\fR
+Export DB contents to \fIFILE\fR.
+Export format is JSON.
+.IP
+FILE can be \fB\-\fR for stdin/stdout or can end in \fB.gz\fR for automatic
+gzip compression.
+.TP
+\fB\-i\fR \fIFILE\fR, \fB\-\-import\fR=\fIFILE\fR
+Import DB contents from \fIFILE\fR as exported by this utility.
+.IP
+FILE can be \fB\-\fR for stdin/stdout or can end in \fB.gz\fR for automatic
+gzip compression.
+.IP
+.B Note:
+The DB must be empty first.
+.TP
+\fB\-u\fR, \fB\-\-upgrade\fR
+Upgrade DB schema to the latest version.
+You need to run this after upgrading your bot.
+.IP
+.B Note:
+You should backup first.
+.SH OPTIONS
+.TP
+\fB\-\-version\fR
+Show the program's version and exit.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Turn on debugging output to stderr.
+.SH FILES
+.TP
+.I ibid.ini
+Locates the database to act upon by looking for the \fB[databases].ibid\fR value
+in the bot configuration file in the current directory.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.BR ibid-setup (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-factpack.1'
--- man/ibid-factpack.1	1970-01-01 00:00:00 +0000
+++ man/ibid-factpack.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,63 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-FACTPACK "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-factpack \- Factoid-package management utility for Ibid
+.SH SYNOPSIS
+.B ibid-factpack
+.RB [ -s ]
+.I factpack-file
+.br
+.B ibid-factpack -r
+.RB [ -f ]
+.I factpack-name
+.br
+.B ibid-factpack -h
+.SH DESCRIPTION
+This utility is for adding and removing sets of packaged factoids, known as
+factpacks, from your Ibid's factoid database.
+.P
+The default mode is factpack loading.
+The \fIfactpack-file\fR specified is loaded into the bot's database.
+Should the pack contain any facts with the same name as an existing fact in the
+bot's database, loading will be aborted, unless the \fB-s\fR option is
+supplied.
+.P
+When invoked with the \fB-r\fR option, the named factpack (original import
+filename minus the extension) will be removed from the bot.
+If any of the facts contained in that pack were modified while loaded in the
+bot, unloading will be aborted, unless the \fB-f\fR option is supplied.
+.SH OPTIONS
+.TP
+\fB\-r\fR, \fB\-\-remove\fR
+Remove the named factpack, rather than importing.
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+Force removal, if facts in the factpack were modified by users.
+.TP
+\fB\-s\fR, \fB\-\-skip\fR
+Skip facts that clash with existing factoids, during import.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.SH FACTPACKS
+Factpacks are JSON-encoded text files containing a list of facts.
+Each fact is a tuple of two lists: fact-names, fact-values.
+The same substitutions are available as in normal online Factoids.
+.SS Example:
+.nf
+[
+ [["Hello", "Hi"], ["<reply> Hi There", "<action> waves"]],
+ [["Bye"], ["<reply> kbye $who", "<reply> Cheers"]]
+]
+.fi
+.SH FILES
+.TP
+.I ibid.ini
+Locates the database to act upon by looking for the \fB[databases].ibid\fR value
+in the bot configuration file in the current directory.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-knab-import.1'
--- man/ibid-knab-import.1	1970-01-01 00:00:00 +0000
+++ man/ibid-knab-import.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,44 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-DB "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-knab-import \- Knab->Ibid Import utility
+.SH SYNOPSIS
+.B ibid-knab-import
+.I knab-sa-url
+.I source
+.RI [ config-file ]
+.SH DESCRIPTION
+This utility imports users, last seen information, factoids, and URLs
+from a Knab bot's database into an Ibid.
+.P
+For best results, import directly into a brand new, clean Ibid install.
+.P
+On import, strings are converted to Unicode, guessing UTF-8 and falling back to
+detection.
+.SH OPTIONS
+.TP
+.I knab-sa-url
+The SQLAlchemy URI for the Knab's database.
+The format is
+.BI mysql:// user : pass @ hostname / dbname
+.TP
+.I source
+The name in the Ibid bot for the source that the Knab was previously connected to.
+.TP
+.I config-file
+If supplied, this is configuration file is used for locating the Ibid's
+database rather than \fBibid.ini\fR.
+.SH FILES
+.TP
+.I ibid.ini
+Locates the database to act upon by looking for the \fB[databases].ibid\fR value
+in the bot configuration file in the current directory.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.BR ibid-setup (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/ ,
+.UR http://knab.omnia.za.net/
+.BR http://knab.omnia.za.net/

=== added file 'man/ibid-memgraph.1'
--- man/ibid-memgraph.1	1970-01-01 00:00:00 +0000
+++ man/ibid-memgraph.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,39 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-MEMGRAPH "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-memgraph \- Memory usage graph generation utility for Ibid
+.SH SYNOPSIS
+.B ibid-memgraph
+.RB [ options ...]
+.I logfile
+.br
+.B ibid-memgraph -h
+.SH DESCRIPTION
+This utility is for graphing memory usage from an Ibid bot configured to
+log such usage.
+.P
+Matplotlib is required for graphing.
+.SH OPTIONS
+.TP
+\fB\-o\fR \fIFILE\fR, \fB\-\-output\fR=\fIFILE\fR
+Output to \fIFILE\fR instead of displaying interactive graph GUI.
+\fIFILE\fR can be any format supported by Matplotlib, detected by the file
+extension.
+.TP
+\fB\-d\fR \fIDPI\fR, \fB\-\-dpi\fR=\fIDPI\fR
+When outputting in raster formats, use \fIDPI\fR output DPI.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.SH FILES
+.TP
+.I logfile
+A log file generated by loading the \fBmemory\fR plugin into Ibid, which will
+periodically log memory usage.
+It can be gzip compressed, if the filename ends in \fB.gz\fR.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid-objgraph (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-objgraph.1'
--- man/ibid-objgraph.1	1970-01-01 00:00:00 +0000
+++ man/ibid-objgraph.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,50 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-OBJGRAPH "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-objgraph \- Memory usage graph generation utility for Ibid
+.SH SYNOPSIS
+.B ibid-objgraph
+.RB [ options ...]
+.IR "logfile type" ...
+.br
+.B ibid-objgraph
+.BI "-e " TIME
+.RB [ options ...]
+.I logfile
+.br
+.B ibid-objgraph -h
+.SH DESCRIPTION
+This utility is for graphing object-type usage from an Ibid bot
+configured to log such usage.
+.P
+Matplotlib is required for graphing.
+.SH OPTIONS
+.TP
+\fB\-e\fR \fITIME\fR, \fB\-\-examine\fR=\fITIME\fR
+Examine the object usage at time \fITIME\fR, and print a sorted list of type
+statistics at that time.
+This function can be useful in determining which types to graph, when chasing
+down a detected leak.
+.TP
+\fB\-o\fR \fIFILE\fR, \fB\-\-output\fR=\fIFILE\fR
+Output to \fIFILE\fR instead of displaying interactive graph GUI.
+\fIFILE\fR can be any format supported by Matplotlib, detected by the file
+extension.
+.TP
+\fB\-d\fR \fIDPI\fR, \fB\-\-dpi\fR=\fIDPI\fR
+When outputting in raster formats, use \fIDPI\fR output DPI.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.SH FILES
+.TP
+.I logfile
+A log file generated by loading the \fBmemory\fR plugin into Ibid, which will
+periodically log object usage.
+It can be gzip compressed, if the filename ends in \fB.gz\fR.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid-memgraph (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-pb-client.1'
--- man/ibid-pb-client.1	1970-01-01 00:00:00 +0000
+++ man/ibid-pb-client.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,54 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-PB-CLIENT "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-pb-client \- RPC Client for Ibid
+.SH SYNOPSIS
+.B ibid-pb-client
+.RI [ options ...]
+.BI message " message"
+.br
+.B ibid-pb-client
+.RI [ options ...]
+.BI plugin " feature method"
+.RI [ parameter ...]
+.br
+.B ibid-pb-client -h
+.SH DESCRIPTION
+This utility is for passing events to a running Ibid bot, or executing
+RPC-exposed functions remotely.
+.P
+It communicates with the \fBpb\fR source on the Ibid.
+.P
+.I message
+is a text message as could be sent to the bot by an IM source.
+The message is processed normally by the bot.
+.P
+.I feature
+is the name of the feature to invoke exposed method \fImethod\fR on,
+directly.
+.IR parameter s
+are passed directly to the method.
+They can be specified positionally or by key, using the same syntax as
+Python:
+.IR key = value .
+They may be encoded in JSON, if not valid JSON they will be treated as
+strings.
+.P
+The output is a JSON-encoded response.
+.SH OPTIONS
+.TP
+\fB\-s\fR \fIHOSTNAME\fR, \fB\-\-server\fR=\fISERVER\fR
+Connect to the Ibid running on \fISERVER\fR, by default it connects to
+\fIlocalhost\fR.
+.TP
+\fB\-p\fR \fIFILE\fR, \fB\-\-port\fR=\fIPORT\fR
+Connect to the \fBpb\fR source running on port \fIPORT\fR, by default
+8789.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.SH SEE ALSO
+.BR ibid (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-plugin.1'
--- man/ibid-plugin.1	1970-01-01 00:00:00 +0000
+++ man/ibid-plugin.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,66 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-PLUGIN "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-plugin \- Plugin testing developer environment for Ibid
+.SH SYNOPSIS
+.B ibid-plugin
+.RI [ options ...]
+.RI [ plugin\fR[\fB- ]| plugin\fB.\fIProcessor [\fB-\fR]...]
+.SH DESCRIPTION
+This utility is for testing Ibid plugins without the full bot
+environment.
+This means testing can be performed offline and without loading all the
+available plugins.
+.P
+This should be run in a configured Ibid bot directory.
+.P
+All the listed plugins and Processors will be loaded on start-up.
+Naming a plugin loads the complete plugin.
+Suffixing a \fB-\fR to the name, ignores that plugin or Processor
+instead of loading it.
+.SH OPTIONS
+.TP
+\fB\-c\fR, \fB\-\-configured\fR
+Load all configured plugins, instead of only the core and requested
+plugins.
+.TP
+\fB\-o\fR, \fB\-\-only\fR
+Don't load the Ibid core plugins, only the plugins requested.
+Note that without the \fBcore\fR plugin to pre- and post-process events,
+most other plugins won't function correctly.
+.TP
+\fB\-p\fR, \fB\-\-public\fR
+By default, \fBibid-plugin\fR emulates a private conversation with the
+bot.
+With this option, the conversation is considered to be public.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show a help message and exit.
+.SH FILES
+.TP
+.I ibid.ini
+Locates the database to act upon by looking for the \fB[databases].ibid\fR value
+in the bot configuration file in the current directory.
+.SH BUGS
+\fBibid-plugin\fR doesn't emulate a complete Ibid environment, and will
+ignore all of the following:
+.TP
+*
+Delayed and periodically executed functions.
+.TP
+*
+Messages to alternate sources.
+.TP
+*
+Messages directly dispatched, rather than added to responses.
+.TP
+*
+Permissions.
+All permissions are granted to the user.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.BR ibid-setup (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid-setup.1'
--- man/ibid-setup.1	1970-01-01 00:00:00 +0000
+++ man/ibid-setup.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,33 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID-SETUP "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid-setup \- Create a basic configuration file and database for an Ibid
+bot
+.SH SYNOPSIS
+.B ibid-setup
+.SH DESCRIPTION
+This program sets up everything that a new Ibid bot needs before it can
+run.
+It asks a series of questions about the new bot, and writes out a basic
+configuration file -
+.BR ibid.ini (5)
+- to the current directory.
+It also creates a database for the bot, by default a SQLite database in
+the current directory.
+.P
+This should be run in the directory which will become the new Ibid bot's
+base.
+.P
+Should there be an existing \fBibid.ini\fR in the current directory, it
+will be used, and the only questions asked will be for adding an
+administrative user. These can safely be skipped with a \fB^C\fR.
+.SH FILES
+.TP
+.I ibid.ini
+The Ibid bot's configuration file, will be created if it doesn't exist.
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid.1'
--- man/ibid.1	1970-01-01 00:00:00 +0000
+++ man/ibid.1	2010-01-24 14:59:10 +0000
@@ -0,0 +1,32 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID "1" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid \- Run an Ibid bot
+.SH SYNOPSIS
+.B ibid
+.RI [ config-file ]
+.SH DESCRIPTION
+This runs an Ibid bot in the foreground.
+.P
+There should there be an existing \fBibid.ini\fR (created by
+.BR ibid-setup (1))
+in the current directory or one should be provided on the command line.
+.P
+Where possible, you should run \fBtwistd -n ibid\fR instead of this
+program, as otherwise some classes of errors go unreported.
+.RB "See " BUGS .
+.SH BUGS
+Exceptions in twisted callbacks can go unnoticed in this program.
+That has no harmful effects, but the developers may miss out on some
+good bug reports.
+.SH FILES
+.TP
+.I ibid.ini
+The Ibid bot's configuration file, will be created if it doesn't exist.
+.SH SEE ALSO
+.BR ibid.ini (5),
+.BR ibid-setup (1),
+.BR twistd (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== added file 'man/ibid.ini.5'
--- man/ibid.ini.5	1970-01-01 00:00:00 +0000
+++ man/ibid.ini.5	2010-01-24 14:59:10 +0000
@@ -0,0 +1,113 @@
+.\" Copyright (c) 2010, Stefano Rivera
+.\" Released under terms of the MIT/X/Expat Licence. See COPYING for details.
+.TH IBID.INI "5" "January 2010" "Ibid 0.0" "Ibid - Multi-protocol Bot"
+.SH NAME
+ibid.ini \- Configuration file for Ibid
+.SH DESCRIPTION
+ibid.ini contains all the configuration for an Ibid bot.
+.P
+A complete description of the contents of this file is out of the scope of this
+manpage.
+For more details see the Ibid documentation:
+.UR http://ibid.omnia.za.net/docs/
+.BR http://ibid.omnia.za.net/docs/
+.P
+Lines beginning with \fB#\fR are considered to be comments and ignored.
+To use a \fB#\fR symbol in an option (e.g. an IRC channel name), quote the
+option with double-quotes, e.g.
+.BR channels = """#ibid"","
+.P
+This file will be written to by the bot when configuration settings are
+altered online.
+It can also be edited manually and a running bot told to
+\fB"reload config"\fR.
+Manual edits and comments will be preserved when the bot modifies its
+own configuration, provided that they have not been edited since bot
+start-up or the last config reload.
+.SH SECTIONS
+.SS auth
+Settings related to permissions and authentication.
+Permissions listed in \fBauth.permissions\fR are granted to all users unless
+revoked by source or account.
+.SS sources
+Sources are Ibid connections to an IM service.
+They range from IRC networks to the bot's built-in HTTP server.
+.P
+Each source is configured in a section named after the source.
+The source name will define the driver that the source should use, unless a
+\fBtype\fR option is provided.
+.P
+Sources can be disabled by setting
+.BR disabled = True .
+.SS plugins
+Plugin configuration.
+Each plugin is configured within a section named after the plugin.
+.P
+.TP
+.B cachedir
+The directory that temporary files (such as downloaded data), useful to be the
+bot but expendable, is stored in.
+.TP
+.B core.autoload
+If \fBTrue\fR, all plugins not explicitly ignored will be loaded.
+(Note that some plugins mark themselves as non-auto-loadable).
+Defaults to \fBTrue\fR.
+.TP
+.B core.load
+The list of plugins (or \fBplugin\fR.\fBProcessor\fRs) to load.
+.TP
+.B core.noload
+The list of plugins (or \fBplugin\fR.\fBProcessor\fRs) to ignore and not load.
+.TP
+.B core.names
+The names that the bot should respond to.
+.TP
+.B core.ignore
+Nicks that the bot should completely ignore (e.g. other bots).
+.SH EXAMPLE
+.nf
+botname = joebot
+logging = logging.ini
+
+[auth]
+    methods = password,
+    timeout = 300
+    permissions = +factoid, +karma, +sendmemo, +recvmemo, +feeds, +publicresponse
+
+[sources]
+    [[telnet]]
+    [[timer]]
+    [[http]]
+        url = http://joebot.example.com
+    [[smtp]]
+    [[pb]]
+    [[atrum]]
+        channels = "#ibid",
+        nick = $botname
+        type = irc
+        auth = hostmask, nickserv
+        server = irc.atrum.org
+
+[plugins]
+    cachedir = /tmp/ibid
+    [[core]]
+        names = $botname, bot, ant
+        ignore = ,
+
+[databases]
+    ibid = sqlite:///ibid.db
+.fi
+.SH FILES
+.TP
+.I logging.ini
+A standard Python \fBlogging.config\fR configuration file describing
+loggers, handlers, and formatters for log messages.
+See
+.UR http://docs.python.org/library/logging.html
+.BR http://docs.python.org/library/logging.html
+.SH SEE ALSO
+.BR ibid (1),
+.BR ibid.ini (5),
+.BR twistd (1),
+.UR http://ibid.omnia.za.net/
+.BR http://ibid.omnia.za.net/

=== modified file 'scripts/ibid'
--- scripts/ibid	2010-01-17 20:08:12 +0000
+++ scripts/ibid	2010-01-24 14:59:10 +0000
@@ -8,7 +8,6 @@
 import ibid
 
 parser = OptionParser(usage='%prog [options] <config filename>')
-parser.add_option('-d', '--debug', dest='debug', action='store_true', help='Output debug messages')
 options, args = parser.parse_args(values={})
 
 options['config'] = len(args) > 0 and args[0] or 'ibid.ini'

=== modified file 'scripts/ibid-db'
--- scripts/ibid-db	2010-01-17 20:08:12 +0000
+++ scripts/ibid-db	2010-01-24 14:59:10 +0000
@@ -22,10 +22,14 @@
 from ibid.db.types import IbidUnicode, IbidUnicodeText
 from ibid.utils import ibid_version
 
+version = ibid_version() or "bzr"
+
 parser = OptionParser(usage='%prog [options...]', description=
 """Ibid Database management tool. Used for import, export, and upgrades.
 Export format is JSON. FILE can be - for stdin/stdout or can end
-in .gz for automatic Gzip compression.""")
+in .gz for automatic Gzip compression.""",
+version=("%prog " + version))
+
 commands = OptionGroup(parser, 'Modes')
 commands.add_option('-e', '--export', dest='export', metavar='FILE',
         help='Export DB contents to FILE.')
@@ -102,7 +106,7 @@
 
     output.write(('# Ibid %(version)s Database dump for %(botname)s '
             'made on %(date)s\n') % {
-        'version': ibid_version() or 'bzr',
+        'version': version,
         'botname': ibid.config['botname'],
         'date': datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
     })

=== modified file 'scripts/ibid-factpack'
--- scripts/ibid-factpack	2010-01-17 20:08:12 +0000
+++ scripts/ibid-factpack	2010-01-24 14:59:10 +0000
@@ -2,10 +2,12 @@
 # Copyright (c) 2009-2010, Michael Gorven, Stefano Rivera
 # Released under terms of the MIT/X/Expat Licence. See COPYING for details.
 
-from sys import exit, stderr
+from sys import exit, stderr, path
 from os.path import basename, exists
 from optparse import OptionParser
 
+path.insert(0, '.')
+
 import ibid
 from ibid.compat import json
 from ibid.config import FileConfig

=== renamed file 'scripts/ibid_import' => 'scripts/ibid-knab-import'
--- scripts/ibid_import	2010-01-18 22:13:23 +0000
+++ scripts/ibid-knab-import	2010-01-24 14:59:10 +0000
@@ -2,7 +2,7 @@
 # Copyright (c) 2009-2010, Michael Gorven, Stefano Rivera
 # Released under terms of the MIT/X/Expat Licence. See COPYING for details.
 
-from sys import argv, exit, stderr, stdout
+from sys import argv, path, exit, stderr, stdout
 
 from chardet import detect
 from dateutil.tz import tzlocal, tzutc
@@ -10,6 +10,8 @@
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import sessionmaker
 
+path.insert(0, '.')
+
 from ibid.config import FileConfig
 from ibid.db.models import Identity
 from ibid.plugins.seen import Sighting
@@ -270,7 +272,7 @@
 
 if __name__ == '__main__':
     if len(argv) < 3:
-        print u'Usage: %s <knab database> <source> [<ibid config>]' % argv[:1]
+        print u'Usage: %s <knab database> <source> [<ibid config>]' % argv[0]
         exit(1)
 
     knabengine = create_engine(argv[1])

=== renamed file 'scripts/ibid_pb' => 'scripts/ibid-pb-client'
--- scripts/ibid_pb	2010-01-17 20:08:12 +0000
+++ scripts/ibid-pb-client	2010-01-24 14:59:10 +0000
@@ -2,16 +2,18 @@
 # Copyright (c) 2009, Michael Gorven
 # Released under terms of the MIT/X/Expat Licence. See COPYING for details.
 
-from sys import argv, exit
+from sys import argv, exit, path
 from optparse import OptionParser, OptionGroup
 
 from twisted.spread import pb
 from twisted.internet import reactor
 from twisted.python import util
 
+path.insert(0, '.')
+
 from ibid.compat import json
 
-parser = OptionParser(usage='%prog [options] message <message> | plugin <plugin> <class> <method> <parameters>')
+parser = OptionParser(usage='%prog [options] message <message> | plugin <feature> <method> <parameters>')
 parser.add_option('-s', '--server', help='Hostname of Ibid instance')
 parser.add_option('-p', '--port', help='Port number of Ibid instance')
 

=== modified file 'setup.py'
--- setup.py	2010-01-18 22:13:23 +0000
+++ setup.py	2010-01-24 14:59:10 +0000
@@ -58,8 +58,8 @@
         'scripts/ibid-plugin',
         'scripts/ibid-setup',
         'scripts/ibid-factpack',
-        'scripts/ibid_pb',
-        'scripts/ibid_import',
+        'scripts/ibid-pb-client',
+        'scripts/ibid-knab-import',
         'scripts/ibid.tac',
     ],