misc README formatting tweaks

README.rdoc

@@ -79,7 +79,7 @@ User agent matching:
     # matches non-songbird browsers
   end
 
-= Static files
+== Static files
 
 Put all of your static content in the ./public directory
 
@@ -260,91 +260,75 @@ on Array, Symbol, Fixnum, NilClass.
 
 == Configuration and Reloading
 
-Sinatra supports multiple environments and re-loading.  Re-loading happens on
-every request when in :development.  Wrap your configurations in
-<tt>configure</tt> (i.e. Database connections, Constants, etc.) to protect
-them from re-loading and to only work in certain environments.
+Sinatra supports multiple environments and reloading. Reloading happens
+before every request when running under the :development environment. Wrap
+your configurations in <tt>configure</tt> (i.e. Database connections, Constants,
+etc.) to protect them from reloading or to target specific environments.
 
 All environments:
 
   configure do
-
+    ...
   end
 
-Production
+Production:
 
   configure :production do
-
+    ...
   end
 
 Two at a time:
 
   configure :production, :test do
-
+    ...
   end
 
 This is also really nifty for error handling.
 
-= Error handling
+== Error handling
 
-== Not Found
+Error handlers run inside the current Sinatra::EventContext instance, which
+means you get all the goodies it has to offer (i.e. haml, erb, throw :halt,
+etc.)
 
-Remember:  These are run inside the Sinatra::EventContext which means you get
-all the goodies is has to offer (i.e. haml, erb, :halt, etc.)
+=== Not Found
 
-Whenever NotFound is raised this will be called
+When Sinatra::NotFound is raised, the not_found handler is invoked:
 
   not_found do
     'This is nowhere to be found'
   end
 
-== Error
+=== Error
 
-By default +error+ will catch Sinatra::ServerError
+By default, the +error+ handler is invoked on Sinatra::ServerError or when
+an unknown error occurs.
 
-Sinatra will pass you the error via the 'sinatra.error' in request.env
+The exception can be obtained from the 'sinatra.error' variable in
+request.env.
 
   error do
     'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
   end
 
-Custom error mapping:
+Custom errors:
 
   error MyCustomError do
     'So what happened was...' + request.env['sinatra.error'].message
   end
 
-then if this happens:
+Then, if this happens:
 
   get '/' do
     raise MyCustomError, 'something bad'
   end
 
-you gets this:
+You get this:
 
   So what happened was... something bad
 
-one guess what this does ;)
-
-  not_found do
-    'I have no clue what you're looking for'
-  end
-
-Because Sinatra gives you a default <tt>not_found</tt> and <tt>error</tt> do
-:production that are secure.  If you want to customize only for :production
-but want to keep the friendly helper screens for :development then do this:
-
-  configure :production do
-
-    not_found do
-      "We're so sorry, but we don't what this is"
-    end
-
-    error do
-      "Something really nasty happened.  We're on it!"
-    end
-
-  end
+Sinatra installs special not_found and error handlers when running under
+the development.
 
 == Mime types
 
@@ -360,12 +344,9 @@ interface for Ruby web frameworks. One of Rack's most interesting capabilities
 for application developers is support for "middleware" -- components that sit
 between the server and your application monitoring and/or manipulating the
 HTTP request/response to provide various types of common functionality.
-What's more, middleware is portable between web frameworks, so middleware
-components developed under, e.g., Merb, can be used with Sinatra and vice
-versa.
 
-Sinatra makes building Rack middleware pipelines a cinch via a top-level +use+
-method:
+Sinatra makes building Rack middleware pipelines a cinch via a top-level
++use+ method:
 
   require 'sinatra'
   require 'my_custom_middleware'
@@ -393,20 +374,6 @@ typically don't have to +use+ them explicitly.
 
 == Testing
 
-=== Methods
-
-  get_it path, params
-  get_it path, params.merge(:env => { 'HTTP_HOST' => 'www.sinatrarb.com' }) or
-  get_it path, params.merge(:env => { :host => 'www.sinatrarb.com' })
-
-RESTful:
-
-  post_it '/foo', '<myxml></myxml>', 'HTTP_ACCEPT' => 'application/xml'
-
-also works with:
-
-  get_it, post_it, put_it, delete_it, head_it
-
 === Test/Unit
 
   require 'my_sinatra_app'
@@ -444,15 +411,14 @@ also works with:
 
   end
 
-=== Test Helpers
-
-See Sinatra::Test::Methods
+See Sinatra::Test::Methods for more information on +get_it+, +post_it+,
++put_it+, and friends.
 
 == Command line
 
-Run your sinatra file like:
+Sinatra applications can be run directly:
 
-  ruby myapp.rb [options]
+  ruby myapp.rb [-h] [-x] [-p PORT] [-e ENVIRONMENT]
 
 Options are: