README.md in sprockets-plugin-0.1.2 vs README.md in sprockets-plugin-0.2.0

@@ -1,72 +1,79 @@
 sprockets-plugin
 ================
 
-Package assets into gems for non-Rails applications.
+Package assets into gems for non-Rails Sprockets 2.x applications.
 
 
 Installation
 ------------
 
 ``` bash
 $ gem install sprockets-plugin
 ```
 
 
-Usage
------
+Usage in Applications
+---------------------
 
-Sprockets::Plugin is meant to be used within gems, to package assets for reuse. So the first step is to add it as a dependency in your gemspec:
+To use Sprockets plugins, you only need to do 3 things:
 
+1. Require "sprockets-plugin" to hook everything up.
+   _This may be required by the plugins themselves, but it's best practice to also require this in your application._
+2. Require any plugins you want to use.
+3. Call Sprockets::Environment#append_plugin_paths after setting up your application paths.
+   _Sprockets::Plugin **does not** automatically append paths to the environment. This is because the plugin paths would take precedence over your application's paths._
+   
+Here's an example:
+   
 ``` ruby
-Gem::Specification.new do |s|
-  # ...
-  s.add_runtime_dependency "sprockets-plugin"
+require "sprockets"
+require "sprockets-plugin" # 1.
+require "my_plugin"        # 2.
+
+map "/assets" do
+  env = Sprockets::Environment.new
+  env.append_path "assets/images"
+  env.append_path "assets/javascripts"
+  env.append_path "assets/stylesheets"
+  env.append_plugin_paths # 3.
+  run env
 end
 ```
 
-And then extend Sprockets::Plugin and add the necessary asset paths:
+Usage in Gems
+-------------
 
-``` ruby
-require "sprockets-plugin"
+Sprockets::Plugin is meant to be used within gems, to package assets for reuse. Again, there's only 3 things to do to set this up.
 
-class MyPlugin < Sprockets::Plugin
-  # Set the root path to use relative paths in `.append_path`
-  root File.expand_path("../..", __FILE__)
-  append_path "lib/assets/images"
-  append_path "lib/assets/javascripts"
-  append_path "lib/assets/stylesheets"
-end 
-```
+1. Add it as a dependency in your gemspec.
+2. Extend Sprockets::Plugin.
+3. Add the necessary paths.
 
-Now any assets in the "lib/assets" directory will be available to applications that require this gem:
+`my_plugin.gemspec`:
 
 ``` ruby
-require "sprockets"
-require "my_plugin"
-
-map "/assets" do
-  environment = Sprockets::Environment.new
-  # The assets from MyPlugin will be automatically appended.
-  environment.append_path "assets/images"
-  environment.append_path "assets/javascripts"
-  environment.append_path "assets/stylesheets"
-  run environment
+Gem::Specification.new do |s|
+  # ...
+  s.add_runtime_dependency "sprockets-plugin" # 1.
 end
 ```
 
-Advanced Usage
---------------
+`my_plugin.rb`:
 
-You can package assets for Rails and non-Rails applications in the following way:
-
 ``` ruby
-if defined? Rails
-  require "my_assets/engine"
-elsif defined? Sprockets::Plugin
-  require "my_assets/plugin"
-end
+require "sprockets-plugin"
+
+class MyPlugin < Sprockets::Plugin # 2.
+  # Set the root path to use relative paths in `.append_path`
+  root File.expand_path("../..", __FILE__)
+  
+  append_path "lib/assets/images"      # 3.
+  append_path "lib/assets/javascripts" # 3.
+  append_path "lib/assets/stylesheets" # 3.
+end 
 ```
+
 
 Copyright
 ---------
 
 Copyright (c) 2011 [Peter Browne](http://petebrowne.com). See LICENSE for details.