Documentation cleanups

Fix typos, be more rdocish, and use the README as the main file

4 files changed, 64 insertions, 28 deletions

diff --git a/README b/README
index 3437df9c..7af09f6e 100644
--- a/README
+++ b/README
@@ -1,38 +1,36 @@
-rbot README
-===========
+= rbot - The Ruby IRC bot
 
 rbot is a ruby IRC bot. Think of him as a ruby bot framework with a highly
 modular design based around plugins.
 
-rbot features
-=============
+== rbot features
 
 * Runtime configuration via irc chat
 * User authentication and access levels for using different bot features
-* Built in infobot-style keywords. See example session below.
+* Built in infobot-style keywords.
 * Support for underlying fact database (infobot fact files), which can
   be overridden or supplemented by runtime keyword controls
-* Multi-language support - comes with english, dutch and german definitions
-  so far - more translations welcome
+* Multi-language support - comes with english, dutch, german, french, italian
+  japanese, chinese and russian definitions so far - more translations welcome
 * Powerful plugin architecture, comes with plugins for:
-  o DNS queries
-  o Babelfish translation
-  o Google searching
-  o Excuse generation
-  o Insult generation
-  o Karma
-  o Checking the weather
-  o Querying slashdot
-  o Doing Math
-  o Per-channel quote storage, searching and retrieval
-  o Reminders
-  o rot13 translation
-  o Check the spelling of a word
-  o Webserver Server: header examination
-  o RPG dice rolling
-  o larting people
-  o conversation stats
-  o more... 
+  - DNS queries
+  - Babelfish translation
+  - Google searching
+  - Excuse generation
+  - Insult generation
+  - Karma
+  - Checking the weather
+  - Querying slashdot
+  - Doing Math
+  - Per-channel quote storage, searching and retrieval
+  - Reminders
+  - rot13 translation
+  - Check the spelling of a word
+  - Webserver Server: header examination
+  - RPG dice rolling
+  - larting people
+  - conversation stats
+  - more... 
 
 Thanks are owed to the infobot developers - several of rbot's features are
 inspired by infobot and so are some of the default plugins. Thanks are also
diff --git a/bin/rbot b/bin/rbot
index 382725c2..8e762569 100755
--- a/bin/rbot
+++ b/bin/rbot
@@ -1,5 +1,41 @@
 #!/usr/bin/env ruby
 
+=begin rdoc
+
+= rbot main executable
+
+Usage:
+
+  % rbot [options] [config directory]
+
+== Options
+
+[-h, --help]
+    display a help message and exit
+[-v, --version]
+    display version information and exit
+[-d, --debug]
+    enable debug messages
+[-l, --loglevel _level_]
+    sets the minimum log level verbosity
+[-b, --background]
+    background (daemonize) the bot
+[-p, --pidfile _filename_]
+    write the bot pid to _filename_
+
+The default config directory is <tt>~/.rbot</tt>.
+
+The default pidfile is <tt><i>botdir</i>/rbot.pid</tt>.
+
+The logfile is located at <tt><i>botdir</i>/<i>botname</i>.log</tt>, and
+the default loglevel is 1 (INFO messages). Possible values for the loglevel
+are 0 (DEBUG), 1 (INFO), 2 (WARN), 3 (ERROR), 4 (FATAL).
+
+Please note that the logfile doesn't contain IRC logs (which are located at
+<tt><i>botdir</i>/logs/*</tt>, but only rbot diagnostic messages.
+
+=end
+
 # Copyright (C) 2002 Tom Gilbert.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -143,8 +179,9 @@ if ($opts["help"])
   puts "  -h, --help         this message"
   puts "  -v, --version      version information"
   puts "  -d, --debug        enable debug messages"
+  puts "  -l, --loglevel     sets the log level verbosity"
   puts "  -b, --background   background (daemonize) the bot"
-  puts "  -p, --pidfile      write the bot pid to this file"
+  puts "  -p, --pidfile      write the bot pid to file"
   puts "config directory defaults to ~/.rbot"
   exit 0
 end
diff --git a/docgen b/docgen
index e07cee27..f370f8c2 100755
--- a/docgen
+++ b/docgen
@@ -1,3 +1,4 @@
 #!/bin/sh
-rdoc -a -i 'lib' --exclude 'post-install.rb' --main lib/rbot/ircbot.rb -o doc lib bin/rbot
+rm -rf doc
+rdoc -a -i 'lib' --exclude 'post-install.rb' --main README --title "rbot - The Ruby IRC bot" -o doc lib bin/rbot README
 
diff --git a/lib/rbot/rfc2812.rb b/lib/rbot/rfc2812.rb
index 375bcc1b..b5203648 100644
--- a/lib/rbot/rfc2812.rb
+++ b/lib/rbot/rfc2812.rb
@@ -4,7 +4,7 @@
 # :title: RFC 2821 Client Protocol module
 #
 # This module defines the Irc::Client class, a class that can handle and
-# dispatch messages based on RFC 2821i (Internet Relay Chat: Client Protocol)
+# dispatch messages based on RFC 2821 (Internet Relay Chat: Client Protocol)
 
 module Irc
   # - The server sends Replies 001 to 004 to a user upon