README in quarry-0.5.0 vs README in quarry-0.5.2

@@ -13,72 +13,78 @@
 
 == Features
 
 === Specifications
 
-Quarry's BBD system is uniqe in a few ways. First it utilizes
-Ruby's Execption system to catch Assertions which are defined
-via assertion <i>functors</i>. Eg.
+Quarry's BDD/TDD system is uniqe in a few ways. First it utilizes
+Ruby's Execption system to catch Assertions which are defined via
+assertion <i>functors</i>. Eg.
 
-    require 'quarry/assertion'
-
     4.assert == 5
 
 Because 4 != 5, this expression will raise an Assertion exception.
-Quarry's Specification Runner class is thus just a means of
-running and capturing these assertions.
+Quarry's Specification Runner class is thus just a means of running
+and capturing these assertions.
 
-Quarry's Specifications themselves are simple text files, a practice
+While we used TDD teminology in the above example, Quarry supports
+a range of momenclature to suit the preferences of TDD vs. BDD 
+developers. The abot could just as well been written as:
+
+  4.should == 5
+
+or 
+
+  4.expect == 5
+
+These are effecitvely the same. For the most part the different terms
+do exactly the same thing. Somtimes though they differ to conform with
+the TDD vs. BDD prespective they intend to support.
+
+Quarry's Specifications themselves are simple text files --a practice
 of literal programming. 
 
     Example Specification
     =====================
+
     Shows that the number 5 does not equal 4.
 
-        5.assert! == 4
+        5.should! == 4
 
     But in fact equals 5.
 
-        5.assert == 5
+        5.should == 5
 
-    QED.
+If we run this specification in verbatim mode the output would be identical
+(assuming we did not make a typo and the assertions passed). If there were
+errors or failures, we would see information detaling each.
 
-If we run this specification in verbatim mode the output would identical
-(assuming we did not make a type and the assertions passed).
-If there were errors or assertion failures, we would see information
-detaling each.
-
-As you can see I used Markdown for my spcecification. You can use almost any
-format you like. The only neccesary distiction is that desciption text be
+As you can see, we used Markdown for this spcecification. Almost any
+format can be used. The only neccesary distinction is that desciption text be
 align to the left margin and all specification code be indented. Quarry also
-recognized headers, currently Markdown and RDoc style headers (We'll add
-Textile soon.)
+recognized headers, currently Markdown and RDoc style headers, which covers
+most markup foramts in common use today. While strictly speaking Qaurry
+does not need to recognize headers, it does improve console output a bit
+if it does.
 
-We'll leave discussion of the merits of this system to another place. But
-it should be clear that this approach if especcailly conveniant, allowing
-documentation and specification to seemlessly merge.
+Give this design some though. It should become clear that this approach if
+especially fruitful in that it allows documentation and specification to
+seemlessly merge.
 
 
-=== Stubs
+=== Stubs, Mocks and Spies
 
-Quarry provides a flexible stubbing facility.
+Quarry provides a flexible stubbing and mocking facility.
 
 For now see RDoc API.
 
-
-=== MethodProbe
-
-MethodProbe (aka the Duck Hunter) can dip-down into a method and
-provide a read-out how it functions --known as a <i>method signiture</i>.
-MethodProbe is somewhat expiremental becuase it is runtime bound, so proper
+The Spy/Probe (aka the Duck Hunter) can dip-down into a method and
+provide a read-out how it functions --known as a <i>method signature</i>.
+Probe is somewhat expiremental becuase it is runtime bound, so proper
 execution can not be 100% guarenteed.  It can miss some parts of a method
-due to conditional branching (a probe can;t pretend to be false) and,
+due to conditional branching (a probe can't pretend to be false) and,
 albiet rare, it can also get stuck in an infinite loop a la the
 Halting Problem. Even so, it can be used effectively under controlled
 situations if used with care.
-
-
-=== More to come ....
 
 
 == Copying
 
 Copyright (c) 2007, 2008 Tiger Ops / Thomas Sawyer