Updated README to match wiki; renamed to README.textile, revealing it…

…s true nature.

README → README.textile

@@ -1,4 +1,4 @@
-h1. Restful Authentication Generator
+h1. "Restful Authentication Generator":http://github.com/technoweenie/restful-authentication
 
 This widely-used plugin provides a foundation for securely managing user
 authentication:
@@ -8,25 +8,35 @@ authentication:
 * Account approval / disabling by admin
 * Rudimentary hooks for authorization and access control.
 
-Several features were updated in May, 2008.  The newest version of this plugin
-may be found in
-  http://github.com/technoweenie/restful-authentication/tree/master
-While a "classic" (backward-compatible) version may be found in
-  http://github.com/technoweenie/restful-authentication/tree/classic
+Several features were updated in May, 2008.  
+* "Stable newer version":http://github.com/technoweenie/restful-authentication/tree/master 
+* "'Classic' (backward-compatible) version":http://github.com/technoweenie/restful-authentication/tree/classic
+* "Experimental version":http://github.com/technoweenie/restful-authentication/tree/modular (Much more modular, needs testing & review)
 
   !! important: if you upgrade your site, existing user account !!
   !! passwords will stop working unless you use --old-passwords !!
 
+***************************************************************************
+
+h2. Issue Tracker
+
+Please submit any bugs or annoyances on the lighthouse tracker at
+* "http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview
+
+***************************************************************************
+
+h2. Documentation
+
 This page has notes on
 * "Installation":#INSTALL
-* "Compatibility Warning":#COMPATIBILITY
 * "New Features":#AWESOME
 * "After installing":#POST-INSTALL
 
 See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home
 (or the notes/ directory) if you want to learn more about:
 
-* "Security Design Patterns":Security-Patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
+* "Extensions, Addons and Alternatives":addons such as HAML templates
+* "Security Design Patterns":security-patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
 * [[Authentication]] -- Lets a visitor identify herself (and lay  claim to her corresponding Roles and measure of Trust)
 * "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions.
 * [[Authorization]] and Policy -- Based on trust and identity, what actions may this visitor perform?
@@ -42,6 +52,7 @@ These best version of the release notes are in the notes/ directory in the
 from there.
 
 ***************************************************************************
+
 <a id="AWESOME"/> </a>
 h2. Exciting new features
 
@@ -66,7 +77,7 @@ h3. Other
 * Minor security fixes -- see CHANGELOG
 
 ***************************************************************************
-<a id="COMPATIBILITY"/> </a>
+
 h2. Non-backwards compatible Changes
 
 Here are a few changes in the May 2008 release that increase "Defense in Depth"
@@ -86,16 +97,21 @@ option or write a migration tool and submit it as a patch.  See the
 
 h3. Validations
 
-By default, 
+By default, email and usernames are validated against a somewhat strict pattern; your users' values may be now illegal.  Adjust to suit.
 
 ***************************************************************************
+
 <a id="INSTALL"/> </a>
 h2. Installation
 
 This is a basic restful authentication generator for rails, taken from
 acts as authenticated.  Currently it requires Rails 1.2.6 or above.
 
-To use:
+**IMPORTANT FOR RAILS > 2.1 USERS** To avoid a @NameError@ exception ("lighthouse tracker ticket":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/tickets/2-not-a-valid-constant-name-errors#ticket-2-2), check out the code to have an _underscore_ and not _dash_ in its name: 
+* either use <code>git clone git://github.com/technoweenie/restful-authentication.git restful_authentication</code> 
+* or rename the plugin's directory to be <code>restful_authentication</code> after fetching it.
+
+To use the generator:
 
   ./script/generate authenticated user sessions \
     --include-activation \
@@ -120,10 +136,12 @@ To use:
   activation code.  (@--stateful@ implies @--include-activation@). Based on the
   idea at [[http://www.vaporbase.com/postings/stateful_authentication]]. Passing
   @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip
-  resource generation -- both useful if you've already run this generator.
-
-* --aasm: Works the same as stateful but uses the updated aasm gem
+  resource generation -- both useful if you've already run this generator. 
+  (Needs the "acts_as_state_machine plugin":http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/,
+  but new installs should probably run with @--aasm@ instead.)
 
+* --aasm: Works the same as stateful but uses the "updated aasm gem":http://github.com/rubyist/aasm/tree/master
+
 * --rspec: Generate RSpec tests and Stories in place of standard rails tests.
   This requires the
     "RSpec and Rspec-on-rails plugins":http://rspec.info/
@@ -137,7 +155,6 @@ To use:
 
 * --skip-routes: Don't generate a resource line in @config/routes.rb@
 
-
 ***************************************************************************
 <a id="POST-INSTALL"/> </a>
 h2. After installing
@@ -148,22 +165,49 @@ alter to suit. There are additional security minutae in @notes/README-Tradeoffs@
 
 * Add these familiar login URLs to your @config/routes.rb@ if you like:
 
-     map.signup  '/signup', :controller => 'users',   :action => 'new' @
-     map.login   '/login',  :controller => 'sessions', :action => 'new' @
-     map.logout  '/logout', :controller => 'sessions', :action => 'destroy' @
-
+    <pre><code> 
+    map.signup  '/signup', :controller => 'users',   :action => 'new' 
+    map.login  '/login',  :controller => 'session', :action => 'new'
+    map.logout '/logout', :controller => 'session', :action => 'destroy' 
+    </code></pre>
+
 * With @--include-activation@, also add to your @config/routes.rb@:
-
-    map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil) 
-
+
+    <pre><code> 
+    map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil 
+    </code></pre> 
+
   and add an observer to @config/environment.rb@:
 
+    <pre><code> 
     config.active_record.observers = :user_observer
+    </code></pre> 
+
+  Pay attention, may be this is not an issue for everybody, but if you should
+  have problems, that the sent activation_code does match with that in the
+  database stored, reload your user object before sending its data through email
+  something like:
+
+    <pre><code> 
+    class UserObserver < ActiveRecord::Observer
+      def after_create(user)
+        user.reload
+        UserMailer.deliver_signup_notification(user)
+      end
+      def after_save(user)
+        user.reload
+        UserMailer.deliver_activation(user) if user.recently_activated?
+      end
+    end
+    </code></pre>
+
 
 * With @--stateful@, add an observer to config/environment.rb:
 
+    <pre><code> 
     config.active_record.observers = :user_observer
-
+    </code></pre>
+
   and modify the users resource line to read
 
     map.resources :users, :member => { :suspend   => :put,