Add docs/CONFIGURATION

Signed-off-by: James Vega <jamessan@users.sourceforge.net>

docs/CONFIGURATION

@@ -0,0 +1,191 @@
+Introduction
+------------
+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` plugin
+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: ``config``, ``list``, and ``help``.
+If you don't know how to get help on those commands, take a look at the
+GETTING_STARTED document.
+
+Configuration Registry
+----------------------
+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, `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.
+
+Configuration Groups
+--------------------
+Using the `Config` plugin, you can list values in a subgroup and get or
+set any of the values anywhere in the configuration hierarchy.  For
+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::
+
+  <jemfinch|lambda> @config list supybot
+  <supybot> jemfinch|lambda: @abuse, @capabilities, @commands,
+            @databases, @debug, @directories, @drivers, @log, @networks,
+            @nick, @plugins, @protocols, @replies, @reply,
+            alwaysJoinOnInvite, channels, defaultIgnore,
+            defaultSocketTimeout, externalIP, flush,
+            followIdentificationThroughNickChanges, ident, pidFile,
+            snarfThrottle, upkeepInterval, and user
+
+These are all the configuration groups and values which are under the
+base `supybot` group.  Actually, their full names would each have a
+'supybot.' prepended to them, but it is omitted in the listing in order
+to shorten the output.  The first entries in the output are the groups
+(distinguished by the '@' symbol in front of them), and the rest are the
+configuration values.  The '@' symbol (like the '#' symbol we'll discuss
+later) is simply a visual cue and is not actually part of the name.
+
+Configuration 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 the ``config help`` command.  For example, to see what this
+`supybot.snarfThrottle` configuration variable is all about, we'd do
+this::
+
+  <jemfinch|lambda> @config help supybot.snarfThrottle
+  <supybot> jemfinch|lambda: A floating point number of seconds to
+            throttle snarfed URLs, in order to prevent loops between two
+            bots snarfing the same URLs and having the snarfed URL in
+            the output of the snarf message.  (Current value: 10.0)
+
+Pretty simply, 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.reply.whenAddressedBy.chars
+  <supybot> jemfinch|lambda: '@'
+
+To set this value, just stick an extra argument after the name::
+
+  <jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars @$
+  <supybot> jemfinch|lambda: The operation succeeded.
+
+Now check this out::
+
+  <jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars
+  <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 which the bot was running).  Instead, I'll revert the change::
+
+  <jemfinch|lambda> $config supybot.reply.whenAddressedBy.chars @
+  <supybot> jemfinch|lambda: The operation succeeded.
+  <jemfinch|lambda> $note that this makes no response.
+
+Default Values
+--------------
+If you're ever curious what the default for a given configuration
+variable is, use the ``config default`` command::
+
+  <jemfinch|lambda> @config default supybot.reply.whenAddressedBy.chars
+  <supybot> jemfinch|lambda: ''
+
+Thus, to reset a configuration variable to its default value, you can
+simply say::
+
+  <jemfinch|lambda> @config supybot.reply.whenAddressedBy.chars [config
+                    default supybot.reply.whenAddressedBy.chars]
+  <supybot> jemfinch|lambda: The operation succeeded.
+  <jemfinch|lambda> @note that this does nothing
+
+Simple, eh?
+
+Searching the Registry
+----------------------
+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|lamda> @config search op
+  <supybot> jemfinch|lambda: supybot.plugins.Enforcer.autoOp,
+            supybot.plugins.Enforcer.autoHalfop,
+            supybot.plugins.Enforcer.takeRevenge.onOps,
+            supybot.plugins.Enforcer.cycleToGetOps,
+            supybot.plugins.Topic, supybot.plugins.Topic.public,
+            supybot.plugins.Topic.separator,
+            supybot.plugins.Topic.format,
+            supybot.plugins.Topic.recognizeTopiclen,
+            supybot.plugins.Topic.default,
+            supybot.plugins.Topic.undo.max,
+            supybot.plugins.Relay.topicSync
+
+Sure, it showed 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 are currently 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.
+
+Channel-Specific Configuration
+------------------------------
+Many configuration variables can be specific to individual channels.
+The `Config` plugin provides an easy way to configure something for a
+specific channel; for instance, in order to set the prefix chars for a
+specific channel, do this in that channel::
+
+  <jemfinch|lambda> @config channel supybot.reply.whenAddressedBy.chars !
+  <supybot> jemfinch|lambda: The operation succeeded.
+
+That'll set the prefix chars in the channel from which the message was
+sent to '!'.  Voila, channel-specific values!  Also, note that when
+using the `Config` plugin's ``list`` command, channel-specific values are
+preceeded by a '#' character to indicate such (similar to how '@' is
+used to indicate a group of values).
+
+Editing the Configuration Values by Hand
+----------------------------------------
+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 database 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' while editing
+the files, and no automatic flushing will occur.