Updated a whole lot of documentation.

README

@@ -5,29 +5,16 @@ Read LICENSE.  It's a 2-clause BSD license, but you should read it anyway.
 
 USERS:
 ------
-First, you gotta have Python 2.3 for this.  That's alright, though,
-because Python 2.3 rocks, and you should have it anyway :)
-
-Assuming "python" is in your path and points to Python 2.3 or newer,
-then you need to run this:
-
-python setup.py install
-
-from the untarred directory to install the source files.  Then just
-run supybot-wizard (it's been installed in your path somewhere) to
-create a script that will run your bot as you answered the questions
-in the wizard.
+Read docs/GETTING_STARTED for an introduction to the bot.  Read
+docs/CAPABILITIES to see how to use capabilities more to your
+benefit. 
 
 If you have any trouble, feel free to swing by #supybot on
-irc.freenode.net or irc.oftc.net (we have a supybot there relaying, so
-either network works) and ask questions.  We'll be happy to help
+irc.freenode.net or irc.oftc.net (we have a Supybot there relaying,
+so either network works) and ask questions.  We'll be happy to help
 wherever we can.  And by all means, if you find anything hard to
-understand or think you know of a better way to do something, *please*
-post it on Sourceforge.net so we can improve the bot!
-
-If you want, try out the included default botscripts.  Just be sure to
-actually add an owner user for yourself with supybot-adduser.  (An
-"owner user" is simply one with the owner capability).
+understand or think you know of a better way to do something,
+*please* post it on Sourceforge.net so we can improve the bot!
 
 WINDOWS USERS:
 --------------
@@ -39,14 +26,17 @@ this: C:\Python23\python C:\Python23\Scripts\supybot-wizard
 
 DEVELOPERS:
 -----------
-Read OVERVIEW to see what the modules are used for.  Read EXAMPLE to see some
-examples of callbacks and command written for the bot.  Read STYLE if you ever
-wish to contribute.
+Read OVERVIEW to see what the modules are used for.  Read EXAMPLE to
+see some examples of callbacks and commands written for the bot.
+Read INTEFACES to see what kinds of objects you'll be dealing with.
+Read STYLE if you wish to contribute; all contributed code must meet
+the guidelines set forth there..
 
 Use PyLint.  It's even better than PyChecker.  A sample .pylintrc file
 is included as tools/pylintrc.  Copy this to ~/.pylintrc and you'll be
 able to check your code with the same stringent guidelines I've found
 useful to check my code. (deja vu? :))
 
-If you run the tests on Windows (or on a modem connection), be sure to 
-exclude (test\test.py -e) test\test_Debian.py.  
+Be sure to run "test/test.py --help" to see what options are available
+to you when testing.  Windows users in particular should be sure to
+exclude test_Debian.py and test_Unix.py.

RELNOTES

@@ -1,3 +1,12 @@
+Version 0.77.0
+
+Configuration has been *entirely* redone.  Read the new
+GETTING_STARTED document to see how to work with configuration
+variables now.  Your old botscripts from earlier versions *will not*
+work with the new configuration method.  We'd appreciate it if you'd
+rerun the wizard in order for us to find any bugs that remain in it
+before we officially declare ourselves Beta.
+
 Version 0.76.1
 
 Almost entirely bugfixes, just some minor (and some less minor) bugs

docs/GETTING_STARTED

@@ -12,22 +12,111 @@ Python developers and we like banana splits.
 So what do you do?  First thing you'll want to do is run (with
 root/admin privileges) "python setup.py install".  This will install
 Supybot globally.  If you need to install locally for whatever
-reason, see the addendum near the end of this document. 
+reason, see the addendum near the end of this document.   You'll then
+have several new programs installed where Python scripts are normally
+installed on your system (/usr/bin or /usr/local/bin are common on
+UNIX systems; C:\Python23\Scripts is a common place on Windows; and
+(watch out, this is a long one :))
+/System/Library/Frameworks/Python.framework/Versions/2.3/bin is a
+common place on MacOS X.).  The
+two that might be of particular interest to you, the new user, are
+"supybot" and "supybot-wizard".  The former ("supybot") is the script
+to run an actual bot; the latter ("supybot-wizard") is an in-depth
+wizard that provides a nice user interface for creating configuration
+files for your bot.  We'd prefer you to the use supybot-wizard, but
+if you're in a hurry or don't feel like being asked many questions,
+just run supybot with no arguments and it'll ask you only the
+questions necessary to run a bot.
+
+So after running either of those two programs, you've got a nice
+registry file handy.  If you're not satisfied with your answers to
+any of the questions you were asked, feel free to run the program
+again until you're satisfied with all your answers.  Once you're
+satisfied, though, run the "supybot" program with the registry file
+you created as an argument.  This will start the bot; unless you
+turned off logging to stdout, you'll see some nice log messages
+describing what the bot is doing at any particular moment; it may
+pause for a significant amount of time after saying "Reconnecting to
+..." while the server tries to check its ident.
+
+Ok, so let's assume your bot connected to the server fine 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
+
+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: each plugin has its own configure function that the wizard
+uses to setup the appropriate registry entries if the plugin requires
+any. ### TODO: Make a command to list loadable plugins?
+
+Now, if you do want to play around with loading plugins, you're going
+to need to have the owner capability.
+# TODO: wizard or supybot-adduser.
+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 your owner user and password 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 addhostmask command: it lets you add a hostmask to your user
+record so the bot recognizes you by your hostmask instead of
+requiring you to always identify with it before it recognizes you.
+Use the help command to see how this command works.  Here's how I
+often use it:
+
+addhostmask 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.
+
+# TODO: Explain the Config plugin.
+
+
 ### TODO: Local installs.
 ### TODO: Explain how to run tests?
 
-After that, you'll want to run supybot-wizard and generate yourself a 
-configuration file.  To run this configuration file, you'll want to type 
-"supybot <config file>", replacing <config file> with the name of the
-configuration file you just generated with the supybot-wizard.  The supybot
-program accepts several command-line parameters which you can see by simply
-running "supybot --help"
-
-After that, you should have a bot up and running in the 
-
-# TODO: Identification, owner, etc.
-
 # Common problems
 #   import error in http (relies on python-xml)
 #   import error in database-based plugins.
-#   Can't find the wizard.  Full path on Windows and MacOS X.

docs/INTERFACES

@@ -80,7 +80,11 @@ ircmsgs.IrcMsg:
                        
 irclib.Irc:
 	This is the object to handle everything about IRC except the
-	actual connection to the server itself.
+	actual connection to the server itself.  (*NOTE* that the
+	object actually received by commands in subclasses of
+	callbacks.Privmsg is an IrcObjectProxy, which is described
+	later.  It augments the following interface with several
+	methods of its own to help plugin authors.)
 
 	Interesting Methods:
 		    The two following messages (queueMsg and
@@ -207,3 +211,48 @@ irclib.IrcCallback:
 		    basically, they're given the first chances
 		    on the way in and the last chances on the
 		    way out.
+
+
+callbacks.IrcObjectProxy:
+	IrcObjectProxy is a proxy for an irclib.Irc instance that
+	serves to provide a much fuller interface for handling
+	replies and errors as well as to handle the nesting of
+	commands.  This is what you'll be dealing with almost all the
+	time when writing commands; when writing doCommand methods
+	(the kind you read about in the interface description of
+	irclib.IrcCallback) you'll be dealing with plain old
+	irclib.Irc objects.
+
+	Interesting methods:
+		    reply: Called to reply to the current message
+	            with a string that is to be the reply.
+
+		    replySuccess, replyError: These reply with the
+		    configured responses for success and generic
+		    error, respectively.  If an additional argument
+		    is given, it's (intelligently) appended to the
+		    generic message to be more specific.
+
+		    error: Called to send an error reply to the
+		    current message; not only does the response
+		    indicate an error, but commands that error out
+		    break the nested-command chain, which is
+		    generally useful for not confusing the user :)
+
+		    errorNoCapability: Like error, except it accepts
+		    the capability that's missing and integrates it
+		    into the configured error message for such
+		    things.  Also accepts an additional string for a
+		    more descriptive message, if that's what you
+		    want.
+
+		    errorPossibleBug, errorNotRegistered,
+		    errorNoUser, errorRequiresPrivacy: These methods
+		    reply with the appropriate configured error
+		    message for the conditions in their names; they
+		    all take an additional arguments to be more
+		    specific about the conditions they indicate, but
+		    this argument is very rarely necessary.
+
+		    getRealIrc: Returns the actual Irc object being
+		    proxied for.

docs/RELEASE-CHECKLIST

@@ -2,6 +2,8 @@ These are things not to be forgotten when making a Supybot release:
 
 Update the version in conf.py.
 Update the version in setup.py.
+Make a release-MAJOR_MINOR_PATCHLEVEL tag.  (cvs tag ...)
+Make a release-MAJOR_MINOR_PATCHLEVEL-branch branch tag.  (cvs tag -b ...)
 Remove CVS directories from the tarball.
 Create .tar.gz, .tar.bz2, and .zip archives.
 Add the release to the supybot package in SF.net.
@@ -10,8 +12,8 @@ Announce the release in a News item on SF.net.
 Announce the release on Freshmeat.net.
 Announce the release on PyPI via "python setup.py register".
 Announce the release on the forums.
+Announce the release on comp.lang.python and comp.lang.python.announce.
 Add a topic to #supybot announcing the release.
-Make a release-MAJOR_MINOR_PATCHLEVEL tag.  (cvs tag ...)
-Make a release-MAJOR_MINOR_PATCHLEVEL-branch branch tag.  (cvs tag -b ...)
+Send a GPG-signed tar.gz to vomjom for packing in Debian.