Improve RI page

RI.txt

@@ -1,58 +1,57 @@
 = RI
-== Background
+
 +ri+ is a tool that allows Ruby documentation to be viewed on the command-line.
-It is part of RDoc and is expected to work on any platform supported by Ruby.
 
-+ri+ will be a bit slow the first time that it runs (or any time that the
-underlying documentation changes) because it builds a cache in the +.ri+
-directory within the user's home directory in order to make future accesses
-faster.
+You can use +ri+ to look up information from either the command line or
+interactively.  When you run +ri+ without any arguments it will launch in
+interactive mode.  In interactive mode you can tab-complete class and method
+names.
 
 == Usage
+
 To see information for a class, do:
-  ri class_name
+  ri ClassName
 
-For example, for the +Array+ class, do
+For example, for the Array class, do:
   ri Array
 
+To see information on a method on a class, do:
+  ri ClassName.method
+
+This will show both instance and class methods.  For example, the IO
+class defines both IO::read and IO#read:
+  ri IO.read
+
 To see information for an instance method, do:
-  ri class_name#method_name
+  ri ClassName#method_name
 
 For example, for Array's +join+ method, do:
   ri Array#join
 
 To see information for a class method, do:
-  ri class_name.method_name
+  ri ClassName::method_name
 
 For example, for Module's +private+ method, do:
-  ri Module.private
+  ri Module::private
 
-To search for all methods containing +read+, do:
+To read documentation for all +read+ methods, do:
   ri read
 
-To search for all methods starting with +read+, do:
-  ri '^read'
-
-To search for all +read+ methods, do:
-  ri '^read$'
-
 == Options
+
 +ri+ supports a variety of options, all of which can be viewed via +--help+.
 Of particular interest, are:
-[-d directory]
-  List of directories from which to source documentation in addition to
-  the standard directories.  May be repeated.  This can be used to specify
-  the location of site-specific documentation (which can be generated with
-  RDoc).
-[-i]
-  This makes +ri+ go into interactive mode.  When +ri+ is in interactive mode,
-  it will allow the user to disambiguate lists of methods in case multiple
-  methods match against a method search string.  It also will allow the user
-  to enter in a method name (with auto-completion, if readline is supported)
-  when viewing a class.
-[-T]
+
+[<tt>-f</tt>]
+  Outputs ri data using the selected formatter.  You can see the available
+  formatters in <tt>ri --help</tt>
+[<tt>-T</tt>]
   Send output to stdout, rather than to a pager.
 
 All options also can be specified through the +RI+ environment variable.
 Command-line options always override those specified in the +RI+ environment
 variable.
+
+The +RI_PAGER+ environment variable allows you to choose a particular pager or
+particular options for your pager.
+