Deprecate RubyGems plugin to allow this to be optional, and fixup docs

README.markdown

@@ -1,17 +1,17 @@
 # Hanna — a better RDoc template
 
-Hanna is an RDoc generator that scales. It's implemented in Haml, making the sources clean
-and readable. It's built with simplicity, beauty and ease of browsing in mind. (See more
-in [the wiki][wiki].)
+Hanna is an RDoc generator that scales. It's implemented in Haml, making the
+sources clean and readable. It's built with simplicity, beauty and ease of
+browsing in mind. (See more in [the wiki][wiki].)
 
 Hanna gem is available from [rubygems.org][]:
 
     gem install hanna
 
 The template was created by [Mislav][] and since then has seen contributions from:
 
-1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from the early
-   start and made tons of fixes and enhancements to the template;
+1. [Tony Strauss](http://github.com/DesigningPatterns), who participated from
+   the early start and made tons of fixes and enhancements to the template;
 2. [Hongli Lai](http://blog.phusion.nl/) with the search filter for methods.
 3. [Erik Hollensbe](http://github.com/erikh) a serious refactoring and up to
    date with RDoc 2.5.x.
@@ -27,11 +27,15 @@ An alternative is to set the `RDOCOPT` environment variable:
 
 This will make RDoc always use Hanna unless it is explicitly overridden.
 
-Another neat trick is to put the following line in your .gemrc:
+## Integrating with RubyGems
+
+Another neat trick is to put the following line in your .gemrc, this will make
+RubyGems use Hanna for all rdoc generation:
 
     rdoc: -f hanna
 
-This will make RubyGems use Hanna when generating documentation for installed gems.
+This will make RubyGems use Hanna when generating documentation for installed
+gems.
 
 ### Rake task
 
@@ -44,7 +48,8 @@ add the hanna format argument to your RDoc::Task options:
       rdoc.options.push '-f', 'hanna'
     end
 
-Tip: you can do this in the Rakefile of your Rails project before running `rake doc:rails`.
+Tip: you can do this in the Rakefile of your Rails project before running
+`rake doc:rails`.
 
 Here is an example of a task for the [rdbi library][rdbi]:
 
@@ -66,27 +71,33 @@ Here is an example of a task for the [rdbi library][rdbi]:
 The gem comes with a RubyGems plugin that overrides the gem default arguments
 to RDoc to use Hanna.
 
-To regenerate documentation for a specific gem (say one you installed before
-installing hanna):
+To regenerate documentation for a specific gem, first configure RubyGems to
+use Hanna, by adding the following to your .gemrc:
+
+    rdoc: -f  hanna
+
+Now to regenerate documentation for an already installed gem:
 
-    gem rdoc mygem
+    gem rdoc mygem --overwrite
 
 To regenerate documentation for all gems:
 
-    gem rdoc --all
+    gem rdoc --all --overwrite
 
+To easily browse your newly created documentation, use `gem server`.
 
 ## You can help
 
 Don't like something? Think you can design better? (You probably can.)
 
-I think of Hanna as the first RDoc template that's actually _maintainable_. First thing I
-have done is converted the original HTML template to Haml and Sass, cleaning up and
-removing the (ridiculous amount of) duplication. Also, the template fragments are now in
-_separate files_.
+I think of Hanna as the first RDoc template that's actually _maintainable_.
+First thing I have done is converted the original HTML template to Haml and
+Sass, cleaning up and removing the (ridiculous amount of) duplication. Also,
+the template fragments are now in _separate files_.
 
-Ultimately, I'd like to lose the frameset. Currently that is far from possible because the
-whole RDoc HTML Generator is built for frames. Still, that is my goal.
+Ultimately, I'd like to lose the frameset. Currently that is far from possible
+because the whole RDoc HTML Generator is built for frames. Still, that is my
+goal.
 
 This is git. Fork it, hack away, tell me about it!