Mikaela/Limnoria
1
0
Fork 0
mirror of https://github.com/Mikaela/Limnoria.git synced 2024-12-24 11:42:52 +01:00
Code Issues Projects Releases Wiki Activity

Documentation update.

Browse Source
This commit is contained in:
Jeremy Fincher 2004-02-18 12:13:24 +00:00
parent faa27d573f
commit a97c961b0b
3 changed files with 315 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
docs/CONFIGURATION
View File

@ -1,22 +1,41 @@
Runtime configuration of Supybot is handled via the Config plugin.
You can get/set and list all of your configuration variables using
this plugin. The configuration structure is hierarchical - there is a
base group which contains all of the configuration stuff (which is
simply called "supybot"), and there are subgroups beneath that base
group, some of which contain values (these should be thought of as your
configuration settings). So, everything in the configuration hierarchy
is a group, but not everything in the hierarchy has an associated value.
Let's take a look at a few examples before we dive into the use of the
Config plugin, just to make sure that the configuration structure is
clear first.
So you've got your Supybot up and running and there are some things
you don't like about it. Fortunately for you, chances are that these
things are configurable, and this document is here to tell you how to
configure them.
Configuration of Supybot is handled via the Config plugin, which
controls runtime access to Supybot's registry (the configuration file
generated by the supybot-wizard program you ran). The Config plugins
provides a way to get or set variables, to list the available
variables, and even to get help for certain variables. Take a moment
now to read the help for each of those commands: get, set, list, and
help. If you don't know how to get help on those commands, go ahead
and read our GETTING_STARTED document before this one.
Now, if you're used to the Windows registry, don't worry, Supybot's
registry is completely different. For one, it's completely plain
text. There's no binary database sensitive to corruption, it's not
necessary to use another program to edit it -- all you need is a
simple text editor. But there is at least one good idea in Windows'
registry: hierarchical configuration. Supybot's configuration
variables are organized in a hierarchy: variables having to do with
the way Supybot makes replies all start with supybot.reply; variables
having to do with the way a plugin works all start with
supybot.plugins.Plugin (where Plugin is the name of the plugin in
question). This hierarchy is nice because it means the user isn't
inundated with hundreds of unrelated and unsorted configuration
variables.
Some of the more important configuration values are located directly
under the base group - things like the bot's nick, it's ident, etc.
Along with these config values are a few subgroups that contain other
values. Some of the more prominent subgroups are: plugins (where all
the plugin-specific configuration is held), replies, commands, and
directories. There are other subgroups as well, but these are the ones
we'll use in our example.
under the base group, supybot. Things like the bot's nick, its ident,
etc. Along with these config values are a few subgroups that contain
other values. Some of the more prominent subgroups are: plugins
(where all the plugin-specific configuration is held), reply (where
variables affecting the way a Supybot makes its replies resides),
replies (where all the specific standard replies are kept), and
directories (where all the directories a Supybot uses are defined).
There are other subgroups as well, but these are the ones we'll use in
our example.
Using the Config plugin, you can list the values in a subgroup and get
or set any of the values anywhere in the configuration hierarchy. For
@ -24,33 +43,28 @@ example, let's say you wanted to see what configuration values were
under the "supybot" (the base group) hierarchy. You would simply issue
this command:
config list supybot
Which would return a list of things like this:
nick, ident, user, server, password, channels, prefixChars,
defaultCapabilities, ignores, defaultAllow, defaultIgnore,
humanTimestampFormat, externalIP, pipeSyntax,
followIdentificationThroughNickChanges, alwaysJoinOnInvite,
showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
snarfThrottle, threadAllCommands, httpPeekSize, pingServer,
pingInterval, and flush
<jemfinch|lambda> @config list supybot
<supybot> jemfinch|lambda: nick, ident, user, server,
password, channels, prefixChars, defaultCapabilities,
defaultAllow, defaultIgnore, humanTimestampFormat,
externalIP, pipeSyntax,
followIdentificationThroughNickChanges, alwaysJoinOnInvite,
showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
snarfThrottle, threadAllCommands, pingServer, pingInterval,
upkeepInterval, flush, httpPeekSize, and
defaultSocketTimeout
These are all the configuration values you can set which are under the
base "supybot" group. Actually, their full names would each have a
"supybot." appended on to the front of them, but it is omitted in the
listing to shorten the output and it is assumed since you entered in
"supybot" as the group to look under.
listing in order to shorten the output.
Now, to see all of the available configuration groups under the base
"supybot" group, we simply use the "--groups" flag to config list:
config list --groups supybot
Which returns a list of subgroups, like so:
commands, databases, directories, drivers, log, plugins, replies, and
reply
<jemfinch|lambda> @config list --groups supybot
<supybot> jemfinch|lambda: commands, databases,
directories, drivers, log, plugins, replies, and reply
These are all the subgroups of "supybot". Again, the full name of
these would have "supybot." prepended to them. So really, we have
@ -59,29 +73,117 @@ supybot.commands, supybot.databases, etc.
Note: an item can show up in both lists if it is a group that itself
has a value. For example, all plugins fall under this category, as
their value is a boolean value determining whether or not that plugin
is loaded when the bot is started.
is to be loaded when the bot is started.
One last listing example, and then we'll start actually reading and
modifying the configuration values. It's important to know that when
you provide the group argument to config list that you must always
provide the full name of the group. For example, "config list
commands" would be incorrect, even though we see "commands" in the
listing above. You must include the full name of the parent group as
well. In this case, that would be "supybot", so to list everything in
listing above. Remember, we just shorten the names by the group
we're listing so we can fit more such names in a single message. In
this case, that would be "supybot", so to list everything in
the commands subgroup of supybot, we do:
config list supybot.commands
<jemfinch|lambda> @config list supybot.commands
<supybot> jemfinch|lambda: defaultPlugins
Which returns:
defaultPlugins
Okay, now that you should have the hang of using the Config plugin to
explore all the configuration variables available to you, let's start
looking at those values.
Okay, now that you've used the Config plugin to list configuration
variables, it's time that we start looking at individual variables
and their values.
The first (and perhaps most important) thing you should know about
each configuration variable is that they all have an associated help
string to tell you what they represent. So the first command we'll
cover is "config help". To see the help string for any value or
group, simply use "config help <group|value>":
group, simply use the "config help" command. For example, to see
what this "supybot.prefixChars" configuration variable is all about,
we'd do this:
<jemfinch|lambda> @config help supybot.prefixChars
<supybot> jemfinch|lambda: Determines what prefix
characters the bot will reply to. A prefix character is a
single character that the bot will use to determine what
messages are addressed to it; when there are no prefix
characters set, it just uses its nick.
Pretty simple, eh?
Now, if you're curious what the current value of a configuration
variable is, you'll use the "config" command with one argument, the
name of the variable you want to see the value of:
<jemfinch|lambda> @config supybot.prefixChars
<supybot> jemfinch|lambda: '@'
To set this value, just stick an extra argument after the name:
<jemfinch|lambda> @config supybot.prefixChars @$
<supybot> jemfinch|lambda: The operation succeeded.
Now, check this out:
<jemfinch|lambda> $config supybot.prefixChars
<supybot> jemfinch|lambda: '@$'
Note that we used $ as our prefix character, and that the value of
the configuration variable changed. If I were to use the "flush"
command now, this change would be flushed to the registry file on
disk (this would also happen if I made the bot quit, or pressed
Ctrl-C in the terminal the bot was running in). Instead, I'll
revert the change:
<jemfinch|lambda> $config supybot.prefixChars @
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> $note that this makes no response.
If you're ever curious what the default for a given configuration
variable is, use the "config default" command:
<jemfinch|lambda> @config default supybot.prefixChars
<supybot> jemfinch|lambda: ''
Thus, to reset a configuration variable to its default value, you can
simply say:
<jemfinch|lambda> @config supybot.prefixChars [config default
supybot.prefixChars]
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> @note that this does nothing
Simple, eh?
Now, let's say you want to find all configuration variables that
might be even remotely related to opping. For that, you'll want the
"config search" command. Check this out:
<jemfinch|lambda> @config search op
<supybot> jemfinch|lambda:
supybot.plugins.Enforcer.autoOp,
supybot.plugins.Enforcer.autoOp.#supybot,
supybot.plugins.Enforcer.autoHalfop,
supybot.plugins.Enforcer.cycleToGetOps, supybot.plugins.Topic,
supybot.plugins.Topic.separator, and
supybot.plugins.Relay.topicSync
Sure, it showed up all the topic-related stuff in there, but it also
showed you all the op-related stuff, too. Do note, however, that you
can only see configuration variables for plugins that you have loaded
or that you loaded in the past; if you've never loaded a plugin,
there's no way for the bot to know what configuration variables it
registers.
Some people might like editing their registry file directly rather
than manipulating all these things through the bot. For those
people, we offer the "config reload" command, which reloads both
registry configuration and user/channel/ignore database
configuration. Just edit the interesting files and then give the bot
the "config reload" command and it'll work as expected. Do note,
however, that Supybot flushes his configuration files and databases
to disk every hour or so, and if this happens after you've edited
your configuration files but before you reload your changes, you
could lose the changes you made. To prevent this, set the
supybot.flush value to Off, and no automatic flushing will occur.
Anyway, that's about it for configuration. Have fun, and enjoy your
configurable bot!

146
docs/FAQ Normal file
View File

@ -0,0 +1,146 @@
Q: Why does my bot not recognize me or tell me that I don't have the
"owner" capability?
A: Because you're not given it anything to recognize you from!
You'll need to identify with the bot ("help identify" to see how
that works) or add your hostmask to your user record ("help
addhostmask" to see how that works) for it to know that you're
you. You may wish to note that addhostmask can accept a password;
rather than identify, you can send the command "addhostmask
myOwnerUser [hostmask] myOwnerUserPassword" and the bot will add
your current hostmask to your owner user (of course, you should
change myOwnerUser and myOwnerUserPassword appropriately for your
bot).
Q: How do I make my Supybot op my users?
A: First, you'll have to make sure that your users register with the
bot. They can do this with the "register" command. After they do
so, you'll want to add the #channel,op capability to their user.
Use the "channel addcapability" command to do this. After that,
your users should be able to use the "op" command to get ops.
If you want your users to be auto-opped when they join the
channel, you'll need to load the Enforcer plugin and turn its
autoOp configuration variable on. Use the "config" command to do
so. Here's an example of how to do these steps:
<jemfinch|lambda> I'm going to make an example session for giving
you auto-ops, for our FAQ.
<dunk1> ah ok ;]
<jemfinch|lambda> First, I need you to register with supybot, using
the "register" command (remember to send it in
private).
<dunk1> done
<jemfinch|lambda> what name are you registered under?
<dunk1> dunk1
<jemfinch|lambda> ok, cool.
<jemfinch|lambda> @channel addcapability dunk1 op
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> now use the "op" command to get ops.
<dunk1> @op
--- supybot gives channel operator status to dunk1
<dunk1> works!
<dunk1> ;]
<jemfinch|lambda> @load Enforcer
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> @config supybot.plugins.Enforcer.autoOp.#supybot On
<supybot> jemfinch|lambda: The operation succeeded.
<jemfinch|lambda> ok, now cycle the channel (part and then rejoin)
<-- dunk1 (dunker@freebsd.nl) has left #supybot
--> dunk1 (dunker@freebsd.nl) has joined #supybot
--- supybot gives channel operator status to dunk1
<jemfinch|lambda> cool, thanks :)
Q: Can users with the "admin" capability change configuration
variables?
A: Currently, no. Since this is the first release of Supybot that
uses the registry, we wanted to stay on the conservative side and
require the "owner" capability for changing all
non-channel-related configuration variables. Feel free to make
your case to us as to why a certain configuration variable should
only require the "admin" capability instead of the "owner"
capability, and if we agree with you, we'll change it for the next
release.
Q: How do I make my Supybot connect to multiple servers?
A: You'll need to use the Relay plugin. As long as you don't call
the "relay join" command, it won't actually do any relaying between
channels (even if the bot is on the same channel on different
networks). In order to use the Relay plugin, you'll want to first
call the "relay start" command, followed by the "relay connect"
command. These commands are (unfortunately) not persistent at
this time, so you'll need to give them to the bot anytime you
start it up. We'll probably have this lack of persistence
rectified before the next release.
Q: Can Supybot do factoids?
A: Supybot most certainly can! In fact, we offer two full-fledged
factoids-related plugins!
Factoids (written by jemfinch) is Supybot's original
factoids-related plugin. It offers full integration with Supybot's
nested commands as well as a complete 1:n key to factoid ratio,
with lookup by individual number. Factoids also uses
a channel-specific database instead of a global database, although
in the future it will likely be a configuration option whether to
use channel-specific or global databases for such plugins.
MoobotFactoids (written by Strike) is much more full-featured,
offering users the ability to define factoids in a slightly more
user-friendly way, as well as parsing factoids to handle <reply>,
<action>, "see", and altnerations (defining a factoid "test" as
"<reply>(foo|bar|baz)" will make the bot send "foo" or "bar" or
"baz" to the channel (without the normal "test is " at the
beginning)). If you're accustomed to Moobot's factoids or
Blootbot's factoids, then this is the Factoids plugin for you.
Unfortunately, due to the more natural definition syntax (required
to be compatible with Moobot) you can't define Factoids with
nested commands; you'll have to evaluate the command first and
then copy the result into your factoid definition. MoobotFactoids
uses a global database, so the factoids are the same for all
channels.
In the future, we plan to have a compatibility plugin for Infobot,
but as of present we've not yet written one.
Q: Can I import my Infobot/Blootbot/Moobot factoids into Supybot?
A: As of present, we have no automated way to do so. Strike has
written a few scripts for importing a Moobot database into
MoobotFactoids, however, so you'll want to talk to him about
helping you with that. We're certainly happy to help you convert
such databases; if you can provide us with such a database
exported to a flat file, we can probably do the rest of the work
to write a script that imports it into a database for one of our
factoids-related plugins.
Q: I found a bug, what do I do?
A: Submit it on Sourceforge through our Sourceforge project page:
<http://sourceforge.net/tracker/?group_id=58965&atid=489447>. If
Sourceforge happens to be down when you try to submit your bug,
then post it in the "Supybot Developer Discussion" forum at our
forums at <http://forums.supybot.org/>. If that doesn't work,
email supybot-bugs@lists.sourceforge.net. If that doesn't work,
email jemfinch@supybot.org. If that doesn't work, find yourself
some carrier pigeons and ... hah! You thought I was serious!
Anyway, when you submit your bug, we'll need several things. If
the bug involved an uncaught exception, we need the traceback
(basically the stuff from "Uncaught exception in ..." to the next
log entry). We'd also like to see the commands that caused the
bug, or happened around the time you saw the bug. If the bug
involved a datase, we'd love to see the database. Remember, it's
always worse to send us too much information in a bug report than
too little.

19
docs/GETTING_STARTED
View File

@ -64,6 +64,25 @@ 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".
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: