mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-12-23 19:22:45 +01:00
Documentation update.
This commit is contained in:
parent
faa27d573f
commit
a97c961b0b
@ -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
146
docs/FAQ
Normal 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.
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user