diff --git a/import/ADVANCED_PLUGIN_CONFIG.rst b/develop/advanced_plugin_config.rst similarity index 100% rename from import/ADVANCED_PLUGIN_CONFIG.rst rename to develop/advanced_plugin_config.rst diff --git a/import/ADVANCED_PLUGIN_TESTING.rst b/develop/advanced_plugin_testing.rst similarity index 100% rename from import/ADVANCED_PLUGIN_TESTING.rst rename to develop/advanced_plugin_testing.rst diff --git a/develop/index.rst b/develop/index.rst index 796380b..f4d91e5 100644 --- a/develop/index.rst +++ b/develop/index.rst @@ -4,20 +4,31 @@ Developing plugins for Limnoria ############################### -Doc provided with Supybot: +Generic documentation +~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 1 - ../import/PLUGIN_TUTORIAL.rst - ../import/USING_WRAP.rst - ../import/STYLE.rst - ../import/CONFIGURATION.rst - ../import/USING_UTILS.rst - ../import/ADVANCED_PLUGIN_CONFIG.rst - ../import/ADVANCED_PLUGIN_TESTING.rst + plugin_tutorial.rst + using_wrap.rst + style.rst + using_wrap.rst + style.rst + advanced_plugin_config.rst + advanced_plugin_testing.rst -Other docs: +Specific documentation +~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + using_utils.rst + httpserver.rst + +Library reference +~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 @@ -26,4 +37,3 @@ Other docs: irclib.rst commands.rst ircmsgs.rst - httpserver.rst diff --git a/import/PLUGIN_TUTORIAL.rst b/develop/plugin_tutorial.rst similarity index 100% rename from import/PLUGIN_TUTORIAL.rst rename to develop/plugin_tutorial.rst diff --git a/import/STYLE.rst b/develop/style.rst similarity index 100% rename from import/STYLE.rst rename to develop/style.rst diff --git a/import/USING_UTILS.rst b/develop/using_utils.rst similarity index 100% rename from import/USING_UTILS.rst rename to develop/using_utils.rst diff --git a/import/USING_WRAP.rst b/develop/using_wrap.rst similarity index 100% rename from import/USING_WRAP.rst rename to develop/using_wrap.rst diff --git a/import/GETTING_STARTED.rst b/import/GETTING_STARTED.rst deleted file mode 100644 index 4e825de..0000000 --- a/import/GETTING_STARTED.rst +++ /dev/null @@ -1,181 +0,0 @@ -**************************** -Getting Started with Supybot -**************************** - -Introduction -============ - -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 :) - -You should have already read through our install document (if you had to -manually install) before reading any further. Now we'll give you a whirlwind -tour as to how you can get Supybot setup and use Supybot effectively. - -Initial Setup -============= - -Now that you have Supybot installed, you'll want to get it running. The first -thing you'll want to do is run supybot-wizard. Before running supybot-wizard, -you should be in the directory in which you want your bot-related files to -reside. The wizard will walk you through setting up a base config file for -your Supybot. Once you've completed the wizard, you will have a config file -called botname.conf. In order to get the bot running, run ``supybot -botname.conf``. - -Listing Commands -================ - -Ok, so let's assume your bot connected to the server 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 - -Sometimes more than one plugin will have a given command; for instance, the -"list" command exists in both the Misc and Config plugins (both loaded by -default). List, in this case, defaults to the Misc plugin, but you may want -to get the help for the list command in the Config plugin. In that case, -you'll want to give your command like this:: - - supybot: help config list - -Anytime your bot tells you that a given command is defined in several plugins, -you'll want to use this syntax ("plugin command") to disambiguate which -plugin's command you wish to call. For instance, if you wanted to call the -Config plugin's list command, then you'd need to say:: - - supybot: config list - -Rather than just 'list'. - -Making Supybot Recognize You -============================ - -If you ran the wizard, then it is almost certainly the case that 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 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 give yourself the 'owner' capability, restart the 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:: - - help identify - -And follow the instructions; the command you send will probably look like -this, with 'myowneruser' and 'myuserpassword' 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 'hostmask add' command: it lets you add a hostmask to your -user record so the bot recognizes you by your hostmask instead of requiring -you always to identify with it before it recognizes you. Use the 'help' -command to see how this command works. Here's how I often use it:: - - hostmask add 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. - -Loading Plugins -=============== - -Let's take a look at loading 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. - -If you do want to play around with loading plugins, you're going to need to -have the owner capability. - -Remember earlier when I told you to try ``help load``? That's the very command -you'll be using. Basically, if you want to load, say, the Games plugin, then -``load Games``. Simple, right? If you need a list of the plugins you can load, -you'll have to list the directory the plugins are in (using whatever command -is appropriate for your operating system, either 'ls' or 'dir'). - -Getting More From Your Supybot -============================== - -Another command you might find yourself needing somewhat often is the 'more' -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 default value of -`supybot.replies.genericNoCapability` -- it's so long that it'll stretch -across two messages:: - - $config default - supybot.replies.genericNoCapability - jemfinch|lambda: You're missing some capability - you need. This could be because you actually - possess the anti-capability for the capability - that's required of you, or because the channel - provides that anti-capability by default, or - because the global capabilities include that - anti-capability. Or, it could be because the - channel or the global defaultAllow is set to - False, meaning (1 more message) - $more - jemfinch|lambda: that no commands are allowed - unless explicitly in your capabilities. Either - way, you can't do what you want to do. - -So basically, the bot keeps, for each person it sees, a list of "chunks" which -are "released" one at a time by the `more` command. In fact, you can even get -the more chunks for another user: if you want to see another chunk in the last -command jemfinch gave, for instance, you would just say `more jemfinch` after -which, his "chunks" now belong to you. So, you would just need to say `more` -to continue seeing chunks from jemfinch's initial command. - -Final Word -========== - -You should now have a solid foundation for using Supybot. You can use the -`list` command to see what plugins your bot has loaded and what commands are -in those plugins; you can use the 'help' command to see how to use a specific -command, and you can use the 'more' command to continue a long response from -the bot. With these three commands, you should have a strong basis with which -to discover the rest of the features of Supybot! - -Do be sure to read our other documentation and make use of the resources we -provide for assistance; this website and, of course, #supybot on -irc.freenode.net if you run into any trouble! diff --git a/import/README b/import/README deleted file mode 100644 index edd93f1..0000000 --- a/import/README +++ /dev/null @@ -1 +0,0 @@ -This files were imported from Supybot source code. diff --git a/import/CAPABILITIES.rst b/use/capabilities.rst similarity index 100% rename from import/CAPABILITIES.rst rename to use/capabilities.rst diff --git a/import/CONFIGURATION.rst b/use/configuration.rst similarity index 100% rename from import/CONFIGURATION.rst rename to use/configuration.rst diff --git a/import/FAQ.rst b/use/faq.rst similarity index 100% rename from import/FAQ.rst rename to use/faq.rst diff --git a/use/getting_started.rst b/use/getting_started.rst index e2e0f23..49edd95 100644 --- a/use/getting_started.rst +++ b/use/getting_started.rst @@ -1,38 +1,139 @@ -.. highlight:: none - .. _getting-started: **************************** -Getting started with Supybot +Getting Started with Supybot **************************** -Conventions used by Supybot and this document -============================================= +Introduction +============ -Vocabulary ----------- +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 :) -Plugin - A plugin contains commands. A plugin can be loaded and unloaded on - the fly, as you wish. - Plugin names are always capitalized, and may contain other uppercase - letter, as a separation between two words, because they cannot contain - spaces. +You should have already read through our install document (if you had to +manually install) before reading any further. Now we'll give you a whirlwind +tour as to how you can get Supybot setup and use Supybot effectively. -Command - Commands can be called by users of the bot. - Command names are always lowercased; they always have an help message, that - can be requested at any moment +Initial Setup +============= -Argument - Most of the commands requires arguments, in order to give them more - informations about what you want it to do. +Now that you have Supybot installed, you'll want to get it running. The first +thing you'll want to do is run supybot-wizard. Before running supybot-wizard, +you should be in the directory in which you want your bot-related files to +reside. The wizard will walk you through setting up a base config file for +your Supybot. Once you've completed the wizard, you will have a config file +called botname.conf. In order to get the bot running, run ``supybot +botname.conf``. -Configuration variable - A configuration variable is set either by a bot owner or by a channel op. +Listing Commands +================ -Syntax of the commands ----------------------- +Ok, so let's assume your bot connected to the server 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 + +Sometimes more than one plugin will have a given command; for instance, the +"list" command exists in both the Misc and Config plugins (both loaded by +default). List, in this case, defaults to the Misc plugin, but you may want +to get the help for the list command in the Config plugin. In that case, +you'll want to give your command like this:: + + supybot: help config list + +Anytime your bot tells you that a given command is defined in several plugins, +you'll want to use this syntax ("plugin command") to disambiguate which +plugin's command you wish to call. For instance, if you wanted to call the +Config plugin's list command, then you'd need to say:: + + supybot: config list + +Rather than just 'list'. + +Making Supybot Recognize You +============================ + +If you ran the wizard, then it is almost certainly the case that 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 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 give yourself the 'owner' capability, restart the 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:: + + help identify + +And follow the instructions; the command you send will probably look like +this, with 'myowneruser' and 'myuserpassword' 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 'hostmask add' command: it lets you add a hostmask to your +user record so the bot recognizes you by your hostmask instead of requiring +you always to identify with it before it recognizes you. Use the 'help' +command to see how this command works. Here's how I often use it:: + + hostmask add 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. + +Loading Plugins +=============== + +Let's take a look at loading 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. + +If you do want to play around with loading plugins, you're going to need to +have the owner capability. + +Remember earlier when I told you to try ``help load``? That's the very command +you'll be using. Basically, if you want to load, say, the Games plugin, then +``load Games``. Simple, right? If you need a list of the plugins you can load, +you'll have to list the directory the plugins are in (using whatever command +is appropriate for your operating system, either 'ls' or 'dir'). + +Understanding the help syntax +============================= The syntax of a command describes how to run a command. The syntax is given by the help command. @@ -76,37 +177,52 @@ utilities last [ ...] You have to give at least one argument, but you can give as many as you wish. -Basics -====== +Getting More From Your Supybot +============================== -Identifying with the bot ------------------------- +Another command you might find yourself needing somewhat often is the 'more' +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 default value of +`supybot.replies.genericNoCapability` -- it's so long that it'll stretch +across two messages:: -Everything you want to do with your bot should be done on IRC (apart starting -the bot, of course). That's why the first thing you need to do is getting your -bot know your are its owner, unless what it won't obey you for administrative -commands. + $config default + supybot.replies.genericNoCapability + jemfinch|lambda: You're missing some capability + you need. This could be because you actually + possess the anti-capability for the capability + that's required of you, or because the channel + provides that anti-capability by default, or + because the global capabilities include that + anti-capability. Or, it could be because the + channel or the global defaultAllow is set to + False, meaning (1 more message) + $more + jemfinch|lambda: that no commands are allowed + unless explicitly in your capabilities. Either + way, you can't do what you want to do. -Open a query window with the bot (make sure this is your bot), and write in -it:: - - identify +So basically, the bot keeps, for each person it sees, a list of "chunks" which +are "released" one at a time by the `more` command. In fact, you can even get +the more chunks for another user: if you want to see another chunk in the last +command jemfinch gave, for instance, you would just say `more jemfinch` after +which, his "chunks" now belong to you. So, you would just need to say `more` +to continue seeing chunks from jemfinch's initial command. -where ** and ** are the name and the password you gave to the -*supybot-wizard*. +Final Word +========== -Sending the bot a command -------------------------- +You should now have a solid foundation for using Supybot. You can use the +`list` command to see what plugins your bot has loaded and what commands are +in those plugins; you can use the 'help' command to see how to use a specific +command, and you can use the 'more' command to continue a long response from +the bot. With these three commands, you should have a strong basis with which +to discover the rest of the features of Supybot! -There are four ways to ask the bot to do something: - -* Give the command in private; -* Give the command on a channel with a prefix character, either set in the - wizard or in the configuration; -* Give the command on a channel prefixed by the nick; -* Give the command on a channel, prefixed by a string of characters, set in - the config. - -In this documentation, we the bot is called *mybot*, and its prefix char is @, -because @ is the most common prefix for Supybot; and the bot doesn't have a -prefix string of characters. +Do be sure to read our other documentation and make use of the resources we +provide for assistance; this website and, of course, #supybot on +irc.freenode.net if you run into any trouble! diff --git a/use/index.rst b/use/index.rst index eb4bfaf..417487f 100644 --- a/use/index.rst +++ b/use/index.rst @@ -9,7 +9,8 @@ The Supybot user guide install.rst getting_started.rst + configuration.rst + capabilities.rst + faq.rst plugins/index.rst - ../import/CAPABILITIES.rst - ../import/FAQ.rst httpserver.rst