Readme.md in surrogate-0.5.1 vs Readme.md in surrogate-0.5.2

@@ -1,5 +1,7 @@
+
+
 About
 =====
 
 Handrolling mocks is the best, but involves more overhead than necessary, and usually has less helpful
 error messages. Surrogate addresses this by endowing your objects with common things that most mocks need.
@@ -11,11 +13,32 @@
 for changes to a. Depending on the internals of the code (anything not shown in the readme) is
 discouraged at this time. If you do want to do this (e.g. to make an interface for test/unit)
 let me know, and I'll inform you / fork your gem and help update it, for any breaking changes
 that I introduce.
 
+New Syntax
+==========
 
+Recently (v0.5.1), a new syntax was added:
+
+<table>
+  <tr><th>Old</th><th>New</th></tr>
+  <tr><td>.should have_been_told_to</td><td>.was told_to</td></tr>
+  <tr><td>.should have_been_asked_for_its</td><td>.was asked_for</td></tr>
+  <tr><td>.should have_been_asked_if</td><td>.was asked_if</td></tr>
+  <tr><td>.should have_been_initialized_with</td><td>.was initialized_with</td></tr>
+</table>
+
+If you want to switch over, here is a shell script that should get you pretty far:
+
+    find spec -type file |
+      xargs ruby -p -i.old_syntax \
+      -e 'gsub /should(_not)?(\s+)have_been_told_to/,               "was\\1\\2told_to"' \
+      -e 'gsub /should(_not)?(\s+)have_been_asked_(if|for)(_its)?/, "was\\1\\2asked_\\3"' \
+      -e 'gsub /should(_not)(\s+)have_been_initialized_with/,       "was\\1\\2initialized_with"' \
+
+
 Features
 ========
 
 * Declarative syntax
 * Support default values
@@ -198,11 +221,11 @@
 ```ruby
 mp3.info :title
 mp3.should have_been_asked_for_its(:info).with(:title)
 ```
 
-Supports RSpec's `no_args` matcher (the others coming in future versions)
+Supports RSpec's matchers (`no_args`, `hash_including`, etc)
 
 ```ruby
 mp3.info
 mp3.should have_been_asked_for_its(:info).with(no_args)
 ```
@@ -420,17 +443,21 @@
 
 
 TODO
 ----
 
+* Remove dependency on all of RSpec and only depend on rspec-core, then have AC tests for the other shit
+* Move surrogates to be first class and defined in the classes that use them.
 * Add proper failure messages for block invocations
 * Add a better explanation for motivations
 * Figure out whether I'm supposed to be using clone or dup for the object -.^ (looks like there may also be an `initialize_copy` method I can take advantage of instead of crazy stupid shit I'm doing now)
 * don't blow up when delegating to the Object#initialize with args (do I still want this, or do I want to force arity matching (and maybe even variable name matching)?)
 * config: rspec_mocks loaded, whether unprepared blocks should raise or just return nil
 * extract surrogate/rspec into its own gem
 * support subset-substitutabilty not being able to touch real methods (e.g. #respond_to?)
 * Add a last_instance option so you don't have to track it explicitly
+* make substitutability matcher go either way
+* make substitutability matcher not care whether either are surrogates
 
 
 Future Features
 ---------------