Limnoria/docs/DocBook/getting_started.sgml

<!DOCTYPE article SYSTEM "supybot.dtd">

<article>
    <articleinfo>
	    <authorgroup>
		    <author>
			    <firstname>Jeremiah</firstname>
				<surname>Fincher</surname>
	        </author>
			<editor>
				<firstname>Daniel</firstname>
				<surname>DiPaolo</surname>
				<contrib>DocBook translator</contrib>
			</editor>
		</authorgroup>
		<title>Getting started with Supybot</title>
		<revhistory>
			<revision>
				<revnumber>0.1</revnumber>
				<date>18 Feb 2004</date>
				<revremark>Initial Docbook translation</revremark>
			</revision>
		</revhistory>
	</articleinfo>
	<sect1>
		<title>Introduction</title>
		<para>
			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 :)
		</para>
		<para>
			First things first: Supybot <emphasis>requires</emphasis> 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, <emphasis>we're</emphasis>
			Python developers and we like banana splits.
		</para>
	</sect1>
	<sect1>
	    <title>Installing the bot and its utilities</title>
		<para>
			So what do you do?  First thing you'll want to do is run (with
			root/admin privileges) <application>python setup.py
			install</application>.  This will install Supybot globally.  If
			you need to install locally for whatever reason, see this <ulink
			url="http://tinyurl.com/2tb37">forum post</ulink> on how to do so.
			You'll then have several new programs installed where Python
			scripts are normally installed on your system
			(<filename>/usr/bin</filename> or
			<filename>/usr/local/bin</filename> are common on UNIX systems;
			<filename>C:\Python23\Scripts</filename> is a common place on
			Windows; and (watch out, this is a long one :))
			<filename>/System/Library/Frameworks/Python.framework/Versions/2.3/bin</filename>
			is a common place on MacOS X.).  The two that might be of
			particular interest to you, the new user, are
			<script>supybot</script> and
			<script>supybot-wizard</script> The former
			(<script>supybot</script> is the script to run an actual
			bot; the latter (<script>supybot-wizard</script> 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
			<script>supybot-wizard</script>, 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.
		</para>
	</sect1>
	<sect1>
		<title>Firing up the bot for the first time</title>
		<para>
			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
			<script>supybot</script> 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
			"Connecting to ..." while the server tries to check its ident.
		</para>
	</sect1>
	<sect1>
		<title>Your first interactions with the bot</title>
		<para>
			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 <nick>supybot</nick> (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>#channel</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:
		</para>
		<ircsession>
supybot: list
		</ircsession>
		<para>
			Replacing <nick>supybot</nick> 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
			<plugin>Admin</plugin>, <plugin>Channel</plugin>,
			<plugin>Config</plugin>, <plugin>Misc</plugin>,
			<plugin>Owner</plugin>, and <plugin>User</plugin> should be
			there; if you used <script>supybot-wizard</script> to
			create your configuration file you may have many more plugins
			loaded.  The <botcommand>list</botcommand> command can also be used to
			list the commands in a given plugin:
		</para>
		<ircsession>
supybot: list Misc
		</ircsession>
		<para>
			Will list all the commands in the <plugin>Misc</plugin> plugin.  
		</para>
		<sect2>
			<title>Accessing the bot's online help</title>
			<para>
				If you want to see the help for any command, just use
				the <botcommand>help</botcommand> command:
			</para>
			<ircsession>
supybot: help help
supybot: help list
supybot: help load
			</ircsession>
		</sect2>
		<sect2>
			<title>Dealing with ambiguous commands</title>
			<para>
				Sometimes more than one plugin will have a given command; for
				instance, the <botcommand>list</botcommand> command exists in both
				the <plugin>Misc</plugin> and <plugin>Config</plugin>
				plugins (both loaded by default).  <plugin>List</plugin>, in
				this case, defaults to the <plugin>Misc</plugin> plugin, but
				you may want to get the help for the
                <botcommand>list</botcommand>
				command in the <plugin>Config</plugin> plugin.  In that
				case, you'll want to give your command like this:
			</para>
			<ircsession>
supybot: help config list
			</ircsession>
			<para>
				Anytime your bot tells you that a given command is defined in
				several plugins, you'll want to use this syntax
				(<botcommand>plugin command</botcommand>) to disambiguate which
				plugin's command you wish to call.  For instance, if you
				wanted to call the <plugin>Config</plugin> plugin's
				<botcommand>list</botcommand> command, then you'd need to say:
			</para>
			<ircsession>
supybot: config list
			</ircsession>
			<para>
				Rather than just <botcommand>list</botcommand>.
			</para>
		</sect2>
		<sect2>
			<title>Loading plugins</title>
			<para>
				Now that you know how to deal with plugins having commands
				with the same name, let's take a look at loading other
				plugins.  If you didn't use
				<script>supybot-wizard</script>, though, you might
				do well to try it before playing around with loading plugins
				yourself: each plugin has its own
				<function>configure</function> function that the wizard uses
				to setup the appropriate registry entries if the plugin
				requires any.
			</para>
			<sect3>
				<title>Identifying yourself as the bot owner</title>
				<para>
					Now, if you do want to play around with loading plugins,
					you're going to need to have the
                    <capability>owner</capability>
					capability.  If you ran the wizard, then chances are you
					already added an owner user for yourself.  If not,
					however, you can add one via the handy-dandy
					<script>supybot-adduser</script> script.  You'll
					want to run it while the bot is not running (otherwise it
					could overwrite
					<script>supybot-adduser</script>'s changes to
					your user database before you get a chance to reload
					them).  Just follow the prompts, and when it asks if you
					want to give the user any capabilities, say yes and then
					give yourself the <capability>owner</capability> capability
					(without the quotes), restart the bot and you'll be ready
					to load some plugins!
				</para>
				<para>
					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:
				</para>
				<ircsession>
help identify
				</ircsession>
				<para>
					And follow the instructions; the command you send will
					probably look like this, with your owner user and password
					replaced:
				</para>
				<ircsession>
identify myowneruser myuserpassword
				</ircsession>
				<para>
					The bot will tell you that &ldquo;The operation
					succeeded&rdquo; 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 <plugin>Owner</plugin> and <plugin>Admin</plugin>
					plugins, which you may want to take a look at (using the
					<botcommand>list</botcommand> and
                    <botcommand>help</botcommand>
					commands, of course).  One command in particular that you
					might want to use (it's from the <plugin>User</plugin>
					plugin) is the <botcommand>addhostmask</botcommand> 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 <botcommand>help</botcommand> command to see how this
					command works.  Here's how I often use it: 
				</para>
				<ircsession>
addhostmask myuser [hostmask] mypassword
				</ircsession>
				<para>
					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
					<plugin>Misc</plugin> 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
					<literal>mypassword</literal> if I'm not already
					identified with the bot.
				</para>
			</sect3>
		</sect2>
		<sect2>
			<title>The <botcommand>more</botcommand> command</title>
			<para>
				Another command you might find yourself needing somewhat often
				is the <botcommand>more</botcommand> command.  The IRC protocol
				limits messages to 512 bytes, 60 or so of which must be
				devoted to some bookkeeping.  Sometimes, however, Supybot
				wants to send a message that's longer than that.  What it
				does, then, is break it into "chunks" and send the first one,
				following it with "(X more messages)" where X is how many more
				chunks there are.  To get to these chunks, use the more
				command.  One way to try is to look at the listing of
				configuration groups for the bot (more on this in the
				CONFIGURATION document) by giving the command "config list
				supybot".  Last I checked, it'll overflow into a second chunk.
				When you invoke this command, you should see output like:
			</para>
			<ircsession>
&lt;supybot&gt; nick, ident, user, server, password, channels, prefixChars,
	defaultCapabilities, defaultAllow, defaultIgnore,
	humanTimestampFormat, externalIP, bracketSyntax, pipeSyntax,
	followIdentificationThroughNickChanges, alwaysJoinOnInvite,
	showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
	snarfThrottle, threadAllCommands, pingServer, pingInterval,
	upkeepInterval, flush, (1 more message)
			</ircsession>
			<para>
				Now, to see the rest of the output, simply give the command
				<botcommand>more</botcommand>, and it will show you the rest:
			</para>
			<ircsession>
&lt;jemfinch&gt; more
&lt;supybot&gt; httpPeekSize, and defaultSocketTimeout
			</ircsession>
		</sect2>
	</sect1>
	<sect1>
		<title>You're ready!</title>
		<para>
			You should now have a solid foundation for using Supybot.  Be sure
			to check the help that is built-in to the bot itself if you have
			any questions, and enjoy using Supybot!
		</para>
	</sect1>
</article>