README.rdoc in ripl-0.1.2 vs README.rdoc in ripl-0.2.0

@@ -8,29 +8,32 @@
 
     sudo gem install ripl
 
 == Features
 
-* Same as irb
+* Similar to irb
   * Reads ~/.irbrc on startup
   * Appends to ~/.irb_history on exit
   * Autocompletion (from bond)
   * _ for last result
   * Type 'exit' or Ctrl-D to exit
-  * Commandline options: -r, -I, -v
+  * 6 common commandline options: -f, -r, -I, -d, -h, -v
+  * IRB.conf -> Ripl.config
 * Enhancements over irb
+  * ~200 lines vs irb's 5000+ lines
+  * Easily extendable with plugins
+  * Customizable completion and completion of method arguments (from bond)
+  * Easy to create custom shells for gems and apps i.e. Ripl.start
+  * Easy to create and invoke ripl subcommands
   * ~/.irbrc errors caught
-  * Provides hooks for plugins
-  * Method argument and customizable autocompletion (from bond)
-  * Less than 150 loc vs irb's 5000+ loc
-  * Simple configuration i.e. one hash
 * Different from irb
   * No multi-line evaluation
   * No irb subsessions or workspaces
-  * No IRB.conf features i.e. dynamic prompts and auto indent
-  * Most commandline options not supported
+  * No IRB.conf features i.e. preconfigured prompts and auto indent
 
+Note: Irb features not in ripl can be implemented as plugins.
+
 == Philosophy
 
 ripl is a light, flexible repl(shell) meant to lay the foundation for customizable ruby shells. It
 provides an environment for plugins to share and reuse best practices for shells. ripl can be
 easily customized for gems, applications and is even usable on the web (examples forthcoming).
@@ -38,18 +41,41 @@
 == Usage
 
     $ ripl
     >> ...
 
-== Create Custom Shells
+== Plugins
 
-Creating a custom shell is as simple as:
+A ripl plugin is a module that is included into Ripl::Shell or Ripl::Runner. Being simply modules,
+they can be packaged as gems and reused across shells as needed.  ripl highly encourages plugins by
+loading them as early as possible and allowing them to extend most of ripl's functionality.
 
-    #!/usr/bin/env ruby
+As an example plugin, let's color error messages red:
 
+    # Place in ~/.riplrc
+    module Ripl
+      module RedError
+        def format_error(error)
+          "\e[31m#{super}\e[m"
+        end
+      end
+    end
+    Ripl::Shell.send :include, Ripl::RedError
+
+Note this plugin extends format_error() by invoking the original format_error() with super. This is
+possible for any method that is available for extension by plugins. To see methods are available for
+extension, see Ripl::Shell::API and Ripl::Runner::API.
+
+If we want to add a config for this plugin, we can simply add a key to Ripl.config that matches the
+underscored version of the plugin name i.e. Ripl.config[:red_error].
+
+== Create Custom Shells
+
+Creating and starting a custom shell is as simple as:
+
     require 'ripl'
-    # Do whatever setup you want ...
+    # Define plugins, load files, etc...
     Ripl.start
 
 Ripl.start takes options to customize your shell. For example if you wanted to
 start on a specific binding:
 
@@ -61,14 +87,20 @@
 To create one, create an executable in the format ripl-<command> and make sure it's in your shell's
 $PATH. For example, the file 'ripl-my_gem' would be invoked with `ripl my_gem`. Note that with your
 command you can take arguments and parse your options as you please. For an example command,
 see {ripl-rails}[http://github.com/cldwalker/ripl-rails].
 
+== Customize ripl
+
+Since ripl is highly customizable, it loads ~/.riplrc before it does anything. This ruby file should
+require and/or define plugins. Any ripl configurations via Ripl.config should also be done here.
+For an example riplrc, see {mine}[http://github.com/cldwalker/dotfiles/tree/master/.riplrc].
+
 == Credits
 * janlelis for bug fix and tweaks
 
 == irb alternatives
-Some other irb alternatives which I encourage you to check out:
+Some other irb alternatives to check out:
 
 * {ir}[http://github.com/raggi/ir]: nice and light
 * {irb2}[http://github.com/wycats/irb2]: yehuda katz's partial attempt at rewriting irb
 * {dietrb}[http://github.com/alloy/dietrb]: mac and ruby 1.9 specific