README.md in cri-2.0b1 vs README.md in cri-2.0rc1

@@ -1,8 +1,122 @@
 Cri
 ===
 
-Cri is a library for building easy-to-use commandline tools.
+Cri is a library for building easy-to-use commandline tools with support for
+nested commands.
+
+Usage
+-----
+
+The central concept in Cri is the _command_, which has option definitions as
+well as code for actually executing itself. In Cri, the commandline tool
+itself is a command as well.
+
+Here’s a sample command definition:
+
+	command = Cri::Command.define do
+	  name        'dostuff'
+	  usage       'dostuff [options]'
+	  aliases     :ds, :stuff
+	  summary     'does stuff'
+	  description 'This command does a lot of stuff. I really mean a lot.'
+
+	  flag   :h, :help,  'show help for this command' do |value, cmd|
+	    puts cmd.help
+	    exit 0
+	  end
+	  flag   :m, :more,  'do even more stuff'
+	  option :s, :stuff, 'specify stuff to do', :argument => :required
+
+	  run do |opts, args, cmd|
+	    stuff = opts[:stuff] || 'generic stuff'
+	    puts "Doing #{stuff}!"
+
+	    if opts[:more]
+	      puts 'Doing it even more!'
+	    end
+	  end
+	end
+
+To run this command, invoke the `#run` method with the raw arguments. For
+example, for a root command (the commandline tool itself), the command could
+be called like this:
+
+	command.run(ARGS)
+
+Each command has automatically generated help. This help can be printed using
+{Cri::Command#help}; something like this will be shown:
+
+	usage: dostuff [options]
+
+	does stuff
+
+	    This command does a lot of stuff. I really mean a lot.
+
+	options:
+
+	    -h --help      show help for this command
+	    -m --more      do even more stuff
+	    -s --stuff     specify stuff to do
+
+Let’s disect the command definition and start with the first five lines:
+
+	name        'dostuff'
+	usage       'dostuff [options]'
+	aliases     :ds, :stuff
+	summary     'does stuff'
+	description 'This command does a lot of stuff. I really mean a lot.'
+
+These lines of the command definition specify the name of the command (or the
+commandline tool, if the command is the root command), the usage, a list of
+aliases that can be used to call this command, a one-line summary and a (long)
+description. The usage should not include a “usage:” prefix nor the name of
+the supercommand, because the latter will be automatically prepended.
+
+Aliases don’t make sense for root commands, but for subcommands they do.
+
+The next few lines contain the command’s option definitions:
+
+	flag   :h, :help,  'show help for this command' do |value, cmd|
+	  puts cmd.help
+	  exit 0
+	end
+	flag   :m, :more,  'do even more stuff'
+	option :s, :stuff, 'specify stuff to do', :argument => :required
+
+Options can be defined using the following methods:
+
+* {Cri::CommandDSL#option} or {Cri::CommandDSL#opt}
+* {Cri::CommandDSL#flag} (implies forbidden argument)
+* {Cri::CommandDSL#required} (implies required argument)
+* {Cri::CommandDSL#optional} (implies optional argument)
+
+Each of the above methods also take a block, which will be executed when the
+option is found. The argument to the block are the option value (`true` in
+case the option does not have an argument) and the command.
+
+The last part of the command defines the execution itself:
+
+	run do |opts, args, cmd|
+	  stuff = opts[:stuff] || 'generic stuff'
+	  puts "Doing #{stuff}!"
+
+	  if opts[:more]
+	    puts 'Doing it even more!'
+	  end
+	end
+
+The {Cri::CommandDSL#run} method takes a block with the actual code to
+execute. This block takes three arguments: the options, any arguments passed
+to the command, and the command itself.
+
+Commands can have subcommands. For example, the `git` commandline tool would be represented by a command that has subcommands named `commit`, `add`, and so on. Commands with subcommands do not use a run block; execution will always be dispatched to a subcommand (or none, if no subcommand is found).
+
+To add a command as a subcommand to another command, use the {Cri::Command#add_command} method, like this:
+
+	root_cmd.add_command cmd_add
+	root_cmd.add_command cmd_commit
+	root.cmd.add_command cmd_init
 
 Contributors
 ------------
 
 (In alphabetical order)