Limnoria/docs/GETTING_STARTED

Ok, so you've decided to try out Supybot.  That's great!  The more
people who use Supybot, the more people can submit bugs and help us to
make it the best IRC bot in the world :)

First things first: Supybot *requires* Python 2.3.  There ain't no
getting around it.  If you're a Python developer, you probably know
how superior 2.3 is to previous incarnations.  If you're not, just
think about the difference between a bowl of plain vanilla ice cream
and a banana split.  Or something like that.  Either way, *We're*
Python developers and we like banana splits.

So what do you do?  First thing you'll want to do is run (with
root/admin privileges) "python setup.py install".  This will install
Supybot globally.  If you need to install locally for whatever
reason, see the addendum near the end of this document.   You'll then
have several new programs installed where Python scripts are normally
installed on your system (/usr/bin or /usr/local/bin are common on
UNIX systems; C:\Python23\Scripts is a common place on Windows; and
(watch out, this is a long one :))
/System/Library/Frameworks/Python.framework/Versions/2.3/bin is a
common place on MacOS X.).  The
two that might be of particular interest to you, the new user, are
"supybot" and "supybot-wizard".  The former ("supybot") is the script
to run an actual bot; the latter ("supybot-wizard") is an in-depth
wizard that provides a nice user interface for creating configuration
files for your bot.  We'd prefer you to the use supybot-wizard, but
if you're in a hurry or don't feel like being asked many questions,
just run supybot with no arguments and it'll ask you only the
questions necessary to run a bot.

So after running either of those two programs, you've got a nice
registry file handy.  If you're not satisfied with your answers to
any of the questions you were asked, feel free to run the program
again until you're satisfied with all your answers.  Once you're
satisfied, though, run the "supybot" program with the registry file
you created as an argument.  This will start the bot; unless you
turned off logging to stdout, you'll see some nice log messages
describing what the bot is doing at any particular moment; it may
pause for a significant amount of time after saying "Reconnecting to
..." while the server tries to check its ident.

Ok, so let's assume your bot connected to the server fine and joined
the channels you told it to join.  For now we'll assume you named
your bot "supybot" (you probably didn't, but it'll make it much
clearer in the examples that follow to assume that you did).  We'll
also assume that you told it to join #channel (a nice generic name
for a channel, isn't it? :))  So what do you do with this bot that
you just made to join your channel?  Try this in the channel:

supybot: list

Replacing "supybot" with the actual name you picked for your bot, of
course.  Your bot should reply with a list of the plugins he
currently has loaded.  At least Admin, Channel, Config, Misc, Owner,
and User should be there; if you used supybot-wizard to create your
configuration file you may have many more plugins loaded.  The list
command can also be used to list the commands in a given plugin:

supybot: list Misc

Will list all the commands in the Misc plugin.  If you want to see
the help for any command, just use the help command:

supybot: help help
supybot: help list
supybot: help load

Speaking of the load command, that's the command you'll use to load
other plugins.  If you didn't use supybot-wizard, though, you might
do well to try it before playing around with loading plugins
yourself: each plugin has its own configure function that the wizard
uses to setup the appropriate registry entries if the plugin requires
any. ### TODO: Make a command to list loadable plugins?

Now, if you do want to play around with loading plugins, you're going
to need to have the owner capability.
# TODO: wizard or supybot-adduser.
Now, in order for the bot to recognize you as your owner user, you'll
have to identify with the bot.  Open up a query window in your irc
client (/query should do it; if not, just know that you can't
identify in a channel because it requires sending your password to
the bot).  Then type this:

help identify

And follow the instructions; the command you send will probably look
like this, with your owner user and password replaced:

identify myowneruser myuserpassword

The bot will tell you that "The operation succeeded" if you got the
right name and password.  Now that you're identified, you can do
anything that requires any privilege: that includes all the commands
in the Owner and Admin plugins, which you may want to take a look at
(using the list and help commands, of course).  One command in
particular that you might want to use (it's from the User plugin) is
the addhostmask command: it lets you add a hostmask to your user
record so the bot recognizes you by your hostmask instead of
requiring you to always identify with it before it recognizes you.
Use the help command to see how this command works.  Here's how I
often use it:

addhostmask myuser [hostmask] mypassword

You may not have seen that "[hostmask]" syntax before.  Supybot
allows nested commands, which means that any command's output can be
nested as an argument to another command.  The hostmask command from
the Misc plugin returns the hostmask of a given nick, but if given no
arguments, it returns the hostmask of the person giving the command.
So the command above adds the hostmask I'm currently using to my
user's list of recognized hostmasks.  I'm only required to give
mypassword if I'm not already identified with the bot.

# TODO: Explain the Config plugin.


### TODO: Local installs.
### TODO: Explain how to run tests?

# Common problems
#   import error in http (relies on python-xml)
#   import error in database-based plugins.