README.md in safe_cookies-0.2.0 vs README.md in safe_cookies-0.2.1

@@ -1,86 +1,81 @@
 # SafeCookies
 
-This Gem has a middleware that will make all cookies secure. In detail, it will:
+This gem has a middleware that will make all cookies secure. In detail, it will
+to two separate things:
 
-* set all new application cookies 'HttpOnly', unless specified otherwise
-* set all new application cookies 'secure', if the request came via HTTPS and not specified otherwise
-* rewrite request cookies, setting both flags as above
+1) set all new application cookies 'HttpOnly', unless specified otherwise;  
+   set all new application cookies 'secure', if the request came via HTTPS and not specified otherwise
 
+2) rewrite request cookies, setting both flags as above
+
 ## Installation
 
 ### Step 1
-Add this line to your application's Gemfile:
+Add `gem 'safe_cookies'` to your application's Gemfile, then run `bundle install`.
 
-    gem 'safe_cookies'
+### Step 2
+**Rails 3 and 4**: add the following lines to the application block in config/application.rb:
 
-Then run `bundle install`.
+    require 'safe_cookies'
+    config.middleware.insert_before ActionDispatch::Cookies, SafeCookies::Middleware
 
-Though this gem is aimed at Rails applications, you may even use it without
-Rails. In that case, install it with `gem install safe_cookies`.
+**Rails 2:** add the following lines to the initializer block in config/environment.rb:
 
+    require 'safe_cookies'
+    config.middleware.insert_before ActionController::Session::CookieStore, SafeCookies::Middleware
 
-### Step 2
-**Rails 3 and 4**: add the following line in config/application.rb:
 
-    class Application < Rails::Application
-      # ...
-      config.middleware.insert_before ActionDispatch::Cookies, SafeCookies::Middleware
-    end
+Now all your cookies will be made `secure` and `HttpOnly`. But what if you need
+a cookie to be accessible via HTTP or Javascript?
 
-**Rails 2:** add the following lines in config/environment.rb:
+### Having a cookie non-secure or non-HttpOnly
+Tell the middleware which cookies not to make `secure` or `HttpOnly` by
+registering them. Do it either just after the lines you added above or in an
+initializer (e.g. in `config/initializers/safe_cookies.rb`). The `:expire_after` option is required.
 
-    Rails::Initializer.run do |config|
-      # ...
-      require 'safe_cookies'
-      config.middleware.insert_before ActionController::Session::CookieStore, SafeCookies::Middleware
-    end
-
-### Step 3
-Register cookies, either just after the lines you added above or in in an initializer
-(e.g. in `config/initializers/safe_cookies.rb`):
-
     SafeCookies.configure do |config|
-      config.register_cookie :remember_token, :expire_after => 1.year
-      config.register_cookie :last_action, :expire_after => 30.days
       config.register_cookie :default_language, :expire_after => 10.years, :secure => false
       config.register_cookie :javascript_data, :expire_after => 1.day, :http_only => false
     end
 
-If a request has any of those four cookies, the middleware will set them anew. The `remember_token` and
-`last_action` cookies will be made `secure` and `HttpOnly`.
-Since we want to access the default language even if the user comes via HTTP,  the `default_language`
-cookie is not made secure. Analogous, the `javascript_data` cookie will be used by a script and hence is
-not made `HttpOnly`.
+### Employing SafeCookies in apps that are already running in production
+Unfortunately, [the client won't ever tell us](http://tools.ietf.org/html/rfc6265#section-4.2.2)
+if it stores the cookie with flags such as `secure` or which expiry date it
+currently has. Therefore, in order to make the middleware retroactively secure
+cookies owned by the client, you need to register each of those cookies with
+the middleware, specifying their properties.
 
-Available options are: `:expire_after (required), :path, :secure, :http_only`.
+Carefully scan your app for cookies you are using. There's no easy way to find
+out if you missed one (but see below for some help the gem provides).
 
-### Step 4 (important for Rails 2 only)
-Override `SafeCookies::Middleware#handle_unknown_cookies(cookies)` to notify you
-e.g. by email (see "Dealing with unregistered cookies" below).
+    SafeCookies.configure do |config|
+      config.register_cookie :remember_token, :expire_after => 1.year
+      config.register_cookie :last_action, :expire_after => 30.days, :path => '/commerce'
+    end
 
+Available options are: `:expire_after` (required)`, :path, :secure, :http_only`.
 
-## Dealing with unregistered cookies
 
-The middleware is not able to secure cookies without knowing their attributes
-(most importantly: their expiry). Unfortunately, [the client won't ever tell us](http://tools.ietf.org/html/rfc6265#section-4.2.2)
-if it stores the cookie with flags such as "secure" or which expiry date it
-currently has. Therefore, it is important to register all cookies that may be
-sent by the client, specifying their properties. Unregistered cookies cannot be
-secured by the middleware.
+## Dealing with unknown cookies
 
-Unknown cookies are written to the Rails log. When you start implementing the
-middleware, you should closely watch it to find cookies you forgot to register.
-You may overwrite `SafeCookies::Middleware#handle_unknown_cookies(cookies)` in
-the config initializer for customized behaviour (like, notifying you per email).
+There are lots of cookies your application receives that you never did set.
+However, if you want to know about any unknown cookies touching your
+application, SafeCookies offers two ways to achieve this.
 
-You should register any cookie that your application is using.
+1) If you set `config.log_unknown_cookies = true` in the configuration, all
+unknown cookies will be written to the Rails log. When you start implementing
+the middleware, closely watch it to find cookies you forgot to register.
 
+2) You may overwrite `SafeCookies::Middleware#handle_unknown_cookies(cookies)`
+in the config initializer for customized behaviour (like, notifying you per
+email).
 
+
 ## Ignoring cookies
 
-Currently, ignoring cookies only prevents the middleware from writing them to the logs.
+The middleware won't see request cookies that are configured to be ignored. Use this to keep your logs lean, if you are using the `log_unknown_cookies` option.
 
 You can tell the middleware to ignore cookies with the `config.ignore_cookie`
 directive, which takes either a String or a Regex parameter. Be careful when using regular expressions!
 
 
@@ -91,10 +86,10 @@
 Users would get multiple cookies for that domain, leading to issues like being unable to sign in.
 
 The configuration option `config.fix_paths` turns on fixing this error. It requires an option
 `:for_cookies_secured_before => Time.parse('some minutes after you will have deployed')` which reflects the
 point of time from which cookies will be secured with the correct path. The middleware will fix the cookie
-paths by rewriting all cookies that it has already secured, but only if the were secured before the time
+paths by rewriting all cookies that it has already secured, but only if they were secured before the time
 you specified.
 
 
 ## Development