README.rdoc in cache_flow-0.1.0 vs README.rdoc in cache_flow-0.1.1

@@ -1,77 +1,48 @@
-= vestal_versions
+= cache_flow
 
-Finally, DRY ActiveRecord versioning!
+Drop-dead simple XML fragment caching in Builder templates!
 
-<tt>acts_as_versioned</tt>[http://github.com/technoweenie/acts_as_versioned] by technoweenie[http://github.com/technoweenie] was a great start, but it failed to keep up with ActiveRecord's introduction of dirty objects in version 2.1. Additionally, each versioned model needs its own versions table that duplicates most of the original table's columns. The versions table is then populated with records that often duplicate most of the original record's attributes. All in all, not very DRY.
+How is it that RESTful web services riding Rails are such a big thing and there doesn't seem to be one definitive, up-to-date reference as to how to cache the XML output? Well <tt>cache_flow</tt> was built to solve that very problem... and _surprisingly_ easily!
 
-<tt>simply_versioned</tt>[http://github.com/mmower/simply_versioned] by mmower[http://github.com/mmower] started to move in the right direction by removing a great deal of the duplication of acts_as_versioned. It requires only one versions table and no changes whatsoever to existing models. Its versions table stores all of the model attributes as a YAML hash in a single text column. But we could be DRYer!
+You may be saying to yourself, "Yes, Rails web services are cool, but only if you're using ActiveRecord::Base#to_xml." Agree to disagree. The <tt>to_xml</tt> approach is just fine, but it seems like scaffolding. I believe there are some serious advantages to building your XML in the view:
 
-<tt>vestal_versions</tt>[http://github.com/laserlemon/vestal_versions] keeps in the spirit of consolidating to one versions table, polymorphically associated with its parent models. But it goes one step further by storing a serialized hash of _only_ the models' changes. Think modern version control systems. By traversing the record of changes, the models can be reverted to any point in time.
+1. It's the view! You wouldn't build your HTML in the model, so why your XML? (See http://bit.ly/rails-models-are-views)
+2. Flexibility. Name your XML nodes anything you want. You're not tied down to your column (or even method) names.
+3. And now... caching! Cache your XML output like you would your ERB views.
 
-And that's just what <tt>vestal_versions</tt> does. Not only can a model be reverted to a previous version number but also to a date or time!
-
 == Installation
 
 In <tt>environment.rb</tt>:
 
   Rails::Initializer.run do |config|
-    config.gem 'vestal_versions'
+    config.gem 'cache_flow'
   end
 
 At your application root, run:
 
   $ sudo rake gems:install
 
-Next, generate and run the first and last versioning migration you'll ever need:
-
-  $ script/generate vestal_versions_migration
-  $ rake db:migrate
-
 == Example
 
-To version an ActiveRecord model, simply add <tt>versioned</tt> to your class like so:
+To cache a chunk of XML, use the one method that <tt>cache_flow</tt> adds to your Builder instance, aptly named <tt>cache!</tt>:
 
-  class User < ActiveRecord::Base
-    versioned
-  
-    validates_presence_of :first_name, :last_name
-  
-    def name
-      "#{first_name} #{last_name}"
+  xml.users, :type => 'array' do
+    @users.each do |user|
+      xml.cache!(user) do
+        xml.user do
+          xml.first_name user.first_name
+          xml.last_name user.last_name
+        end
+      end
     end
   end
 
-It's that easy! Now watch it in action...
+It's that easy! The <tt>cache!</tt> method takes the same arguments as the <tt>cache</tt> method we all know and love from our ERB views. So in the example above, <tt>user.cache_key</tt> will be automatically used as the cache key. You get all the same goodies as Rails' built-in fragment caching.
 
-  >> u = User.create(:first_name => 'Steve', :last_name => 'Richert')
-  => #<User first_name: "Steve", last_name: "Richert">
-  >> u.version
-  => 1
-  >> u.update_attribute(:first_name, 'Stephen')
-  => true
-  >> u.name
-  => "Stephen Richert"
-  >> u.version
-  => 2
-  >> u.revert_to(:first)
-  => 1
-  >> u.name
-  => "Steve Richert"
-  >> u.version
-  => 1
-  >> u.save
-  => true
-  >> u.version
-  => 3
-  >> u.update_attribute(:last_name, 'Jobs')
-  => true
-  >> u.name
-  => "Steve Jobs"
-  >> u.version
-  => 4
-  >> u.revert_to!(2)
-  => true
-  >> u.name
-  => "Stephen Richert"
-  >> u.version
-  => 5
+== How It Works
+
+Behind the scenes, <tt>cache_flow</tt> is using the same mechanism that's used for caching ERB fragments, only using <tt>XmlMarkup#target!</tt> as its buffer rather than <tt>ActionView::Base#output_buffer</tt>. I'd like to take more credit, but it really _is_ that simple.
+
+== To-Do
+
+* Write tests. Any takers? I'm not very familiar with testing the view layer.