README.rdoc in preferences-0.3.1 vs README.rdoc in preferences-0.4.0

@@ -38,10 +38,21 @@
 attribute accessors on the model, hiding the fact that preferences are stored in
 a separate table and making it dead-simple to define and manage preferences.
 
 == Usage
 
+=== Installation
+
++preferences+ requires an additional database table to work.  You can generate
+a migration for this table like so:
+
+  script/generate preferences
+
+Then simply migrate your database:
+
+  rake db:migrate
+
 === Defining preferences
 
 To define the preferences for a model, you can do so right within the model:
 
   class User < ActiveRecord::Base
@@ -99,12 +110,12 @@
 Reader method:
   user.prefers(:hot_salsa)      # => false
   user.preferred(:language)     # => "English"
 
 Write method:
-  user.set_preference(:hot_salsa, false)      # => false
-  user.set_preference(:language, "English")   # => "English"
+  user.write_preference(:hot_salsa, false)      # => false
+  user.write_preference(:language, "English")   # => "English"
 
 === Accessing all preferences
 
 To get the collection of all custom, stored preferences for a particular record,
 you can access the +stored_preferences+ has_many association which is automatically
@@ -133,11 +144,11 @@
 
   user = User.find(:first)
   car = Car.find(:first)
   
   user.preferred_color = 'red', car
-  # user.set_preference(:color, 'red', car) # The generic way
+  # user.write_preference(:color, 'red', car) # The generic way
 
 This will create a color preference of "red" for the given car.  In this way,
 you can have "color" preferences for different records.
 
 To access the preference for a particular record, you can use the same accessor
@@ -149,28 +160,48 @@
 In addition to grouping preferences for a particular record, you can also group
 preferences by name.  For example,
 
   user = User.find(:first)
   
-  user.preferred_color = 'red', 'automobiles'
-  user.preferred_color = 'tan', 'clothing'
+  user.preferred_color = 'red', :automobiles
+  user.preferred_color = 'tan', :clothing
   
-  user.preferred_color('automobiles')   # => "red"
-  user.preferred_color('clothing')      # => "tan"
+  user.preferred_color(:automobiles)  # => "red"
+  user.preferred_color(:clothing)     # => "tan"
+  
+  user.preferences(:automobiles)      # => {"color"=>"red"}
 
-  user.preferences                # => {"color"=>nil, "automobiles"=>{"color"=>"red"}, "clothing=>{"color=>"tan"}}
-  user.preferences('automobiles') # => {"color"=>"red"}
-
 === Saving preferences
 
 Note that preferences are not saved until the owning record is saved.
 Preferences are treated in a similar fashion to attributes.  For example,
 
   user = user.find(:first)
   user.attributes = {:prefers_hot_salsa => false, :preferred_color => 'red'}
   user.save!
 
 Preferences are stored in a separate table called "preferences".
+
+=== Tracking changes
+
+Similar to ActiveRecord attributes, unsaved changes to preferences can be
+tracked.  For example,
+
+  user.preferred_language               # => "English"
+  user.preferred_language_changed?      # => false
+  user.preferred_language = 'Spanish'
+  user.preferred_language_changed?      # => true
+  user.preferred_language_was           # => "English"
+  user.preferred_language_change        # => ["English", "Spanish"]
+  user.reset_preferred_language!
+  user.preferred_language               # => "English"
+
+Assigning the same value leaves the preference unchanged:
+
+  user.preferred_language               # => "English"
+  user.preferred_language = 'English'
+  user.preferred_language_changed?      # => false
+  user.preferred_language_change        # => nil
 
 == Testing
 
 Before you can run any tests, the following gem must be installed:
 * plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]