diff --git a/docs/GETTING_STARTED b/docs/GETTING_STARTED index 94a51222b..f87dac220 100644 --- a/docs/GETTING_STARTED +++ b/docs/GETTING_STARTED @@ -11,72 +11,70 @@ 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 +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. +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. +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: +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 +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: +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. +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. Now, if you do want to play around with loading plugins, you're going to need to have the owner 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 supybot-adduser script. -You'll want to run it while the bot it's running (otherwise it could +You'll want to run it while the bot is not running (otherwise it could overwrite supybot-adduser'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 @@ -85,9 +83,9 @@ bot and you'll be ready to load some plugins! 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: +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 @@ -103,17 +101,16 @@ 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: +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 +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