Documentation update.

docs/CONFIGURATION

@@ -1,22 +1,41 @@
-Runtime configuration of Supybot is handled via the Config plugin.
+So you've got your Supybot up and running and there are some things
-You can get/set and list all of your configuration variables using
+you don't like about it.  Fortunately for you, chances are that these
-this plugin.  The configuration structure is hierarchical - there is a
+things are configurable, and this document is here to tell you how to
-base group which contains all of the configuration stuff (which is
+configure them.
-simply called "supybot"), and there are subgroups beneath that base
+
-group, some of which contain values (these should be thought of as your
+Configuration of Supybot is handled via the Config plugin, which
-configuration settings).  So, everything in the configuration hierarchy
+controls runtime access to Supybot's registry (the configuration file
-is a group, but not everything in the hierarchy has an associated value.
+generated by the supybot-wizard program you ran).  The Config plugins
-Let's take a look at a few examples before we dive into the use of the
+provides a way to get or set variables, to list the available
-Config plugin, just to make sure that the configuration structure is
+variables, and even to get help for certain variables.  Take a moment
-clear first.
+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.
+under the base group, supybot.  Things like the bot's nick, its ident,
-Along with these config values are a few subgroups that contain other
+etc.  Along with these config values are a few subgroups that contain
-values.  Some of the more prominent subgroups are: plugins (where all
+other values.  Some of the more prominent subgroups are: plugins
-the plugin-specific configuration is held), replies, commands, and
+(where all the plugin-specific configuration is held), reply (where
-directories.  There are other subgroups as well, but these are the ones
+variables affecting the way a Supybot makes its replies resides),
-we'll use in our example.
+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
+<jemfinch|lambda> @config list supybot
-
+<supybot> jemfinch|lambda: nick, ident, user, server,
-Which would return a list of things like this:
+	  password, channels, prefixChars, defaultCapabilities,
-
+	  defaultAllow, defaultIgnore, humanTimestampFormat,
-nick, ident, user, server, password, channels, prefixChars,
+	  externalIP, pipeSyntax,
-defaultCapabilities, ignores, defaultAllow, defaultIgnore,
+	  followIdentificationThroughNickChanges, alwaysJoinOnInvite,
-humanTimestampFormat, externalIP, pipeSyntax,
+	  showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
-followIdentificationThroughNickChanges, alwaysJoinOnInvite,
+	  snarfThrottle, threadAllCommands, pingServer, pingInterval,
-showSimpleSyntax, maxHistoryLength, nickmods, throttleTime,
+	  upkeepInterval, flush, httpPeekSize, and
-snarfThrottle, threadAllCommands, httpPeekSize, pingServer,
+	  defaultSocketTimeout
-pingInterval, and flush
 
 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
+listing in order to shorten the output.
-"supybot" as the group to look under.
 
 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
+<jemfinch|lambda> @config list --groups supybot
-
+<supybot> jemfinch|lambda: commands, databases,
-Which returns a list of subgroups, like so:
+	  directories, drivers, log, plugins, replies, and reply
-
-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
+listing above.  Remember, we just shorten the names by the group
-well.  In this case, that would be "supybot", so to list everything in
+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:
+Okay, now that you've used the Config plugin to list configuration
-
+variables, it's time that we start looking at individual variables
-defaultPlugins
+and their values.
-
-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.
 
 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!

docs/FAQ

@@ -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.

docs/GETTING_STARTED

@@ -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: