README.tmpl in main-0.0.2 vs README.tmpl in main-2.0.0

@@ -1,22 +1,38 @@
 NAME
   main.rb
 
 SYNOPSIS
-  a class factory and dsl for generating real main programs real quick
+  a class factory and dsl for generating command line programs real quick
 
 URI
   http://rubyforge.org/projects/codeforpeople/
   http://codeforpeople.com/lib/ruby/
 
 INSTALL
-  $sudo gem install main
+  gem install main
 
 DESCRIPTION
-  main.rb is a library which simplifies and unifies the details of creating
-  command line programs.  for instance, this program
+  main.rb features the following:
 
+    - unification of option, argument, keyword, and environment parameter
+      parsing
+    - auto generation of usage and help messages
+    - support for mode/sub-commands
+    - io redirection support
+    - logging hooks using ruby's built-in logging mechanism
+    - intelligent error handling and exit codes 
+    - use as dsl or library for building Main objects
+    - parsing user defined ARGV and ENV
+    - zero requirements for understanding the obtuse apis of *any* command
+      line option parsers
+
+  in short main.rb aims to drastically lower the barrier to writing uniform
+  command line applications.
+
+  for instance, this program
+
     require 'main'
 
     Main {
       argument 'foo'
       option 'bar'
@@ -27,14 +43,38 @@
         exit_success!
       end
     }
 
   sets up a program which requires one argument, 'bar', and which may accept one
-  command line switch, '--foo' in addition to the single option which is always
-  accepted and handled appropriately: '--help', '-h'.
+  command line switch, '--foo' in addition to the single option/mode which is always
+  accepted and handled appropriately: 'help', '--help', '-h'.  for the most
+  part main.rb stays out of your command line namespace but insists that your
+  application has at least a help mode/option.
 
-  for simple programs this is a real time saver but it's for more complex
+  main.rb supports sub-commands in a very simple way
+
+    require 'main'
+
+    Main {
+      mode 'install' do
+        def run() puts 'installing...' end
+      end
+
+      mode 'uninstall' do
+        def run() puts 'uninstalling...' end
+      end
+    }
+
+  which allows you a program called 'a.rb' to be invoked as
+
+    ruby a.rb install
+
+  and
+
+    ruby a.rb uninstall
+
+  for simple programs main.rb is a real time saver but it's for more complex
   applications where main.rb's unification of parameter parsing, class
   configuration dsl, and auto-generation of usage messages can really streamline
   command line application development.  for example the following 'a.rb'
   program:
 
@@ -139,15 +179,40 @@
   @samples
 
 DOCS
   test/main.rb
 
-  find lib|xargs -n1 vi -R
+  vim -o lib/main.rb lib/main/*
 
   API section below
 
 HISTORY
+  2.0.0
+    - removed need for proxy.rb via Main::Base.wrap_run!
+    - added error handling hooks for parameter parsing
+    - bundled arrayfields, attributes, and pervasives although gems are tried
+      first
+    - softened error messages for parameter parsing errors: certain classes of
+      errors are now 'softspoken' and print only the message, not the entire
+      stacktrace, to stderr.  much nicer for users.  this is configurable.
+    - added subcommand/mode support
+    - added support for user defined exception handling on top level
+      exceptions/exits
+    - added support for negative arity.  this users ruby's own arity
+      semantics, for example:
+      
+        lambda{|*a|}.arity     == -1
+        lambda{|a,*b|}.arity   == -2
+        lambda{|a,b,*c|}.arity == -3
+        ...
+
+      in otherwords parameters now support 'zero or more', 'one or more' ...
+      'n or more' argument semantics
+
+  1.0.0
+    - some improved usage messages from jeremy hinegardner
+
   0.0.2
     - removed dependancy on attributes/arrayfields.  main now has zero gem
       dependancies.
 
     - added support for io redirection.  redirection of stdin, stdout, and
@@ -250,11 +315,62 @@
   #
     usage <<-txt
       my own usage message
     txt
 
+  ###########################################################################
+  #                         MODE API                                        #
+  ###########################################################################
+  #
+  # modes are class factories that inherit from their parent class.  they can
+  # be nested *arbitrarily* deep.  usage messages are tailored for each mode.
+  # modes are, for the most part, independant classes but parameters are
+  # always a superset of the parent class - a mode accepts all of it's parents
+  # paramters *plus* and additional ones
+  # 
+    option 'inherited-option'
+    argument 'inherited-argument'
 
+    mode 'install' do
+      option 'force' do
+        description 'clobber existing installation'
+      end
+
+      def run
+        inherited_method()
+        puts 'installing...'
+      end
+
+      mode 'docs' do
+        description 'installs the docs'
+
+        def run
+          puts 'installing docs...'
+        end
+      end
+    end
+
+    mode 'un-install' do
+      option 'force' do
+        description 'remove even if dependancies exist'
+      end
+
+      def run
+        inherited_method()
+        puts 'un-installing...'
+      end
+    end
+
+    def run
+      puts 'no mode yo?'
+    end
+
+    def inherited_method
+      puts 'superclass_method...'
+    end
+
+
   ###########################################################################
   #                         PARAMETER API                                   #
   ###########################################################################
   #
   # all the parameter types of argument|keyword|option|environment share this
@@ -305,10 +421,11 @@
     # usage also.
     #
       description 'a long description of foo'
     #
     # arity - indicates how many times the parameter should appear on the
-    # command line.  the default is one.
+    # command line.  the default is one.  negative arities are supported and
+    # follow the same rules as ruby methods/procs.
     #
       arity 2
     #
     # default - you can provide a default value in case none is given.  the
     # alias 'defaults' reads a bit nicer when you are giving a list of