README in quarry-0.3.0 vs README in quarry-0.4.0

@@ -3,73 +3,87 @@
   http://quarry.rubyforge.org
 
 
 == Introduction
 
-Ruby Quarry is a developers testing and debuging suite.
-It features a flexible BDD specification system and 
-a number of useful tools.
+Ruby Quarry is a developers testing and debugging suite.
+It features a literal-programming BDD specification system,
+and exception based assertion system, and a few other of
+useful QA tools.
 
 
 == Features
 
-=== Design::Specification
+=== Specifications
 
-Quarry's BBD system is uniqe in two ways. First it utilizes Ruby's
-Execption system to catch Assertions which are define via
-with assertion <i>functors</i>. Eg.
+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.
 
     require 'quarry/assertion'
 
-    4.assert = 5
+    4.assert == 5
 
-This will raise ans Assertion error. Quarry's design specification
-then is just a measn of outlining and capturing these
-assertions.
+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.
 
-The sepcification themeleleves are completely freewform. There is
-no enforced nomenclature. Eg.
+Quarry's Specifications themselves are simple text files, a practice
+of literal programming. 
 
-    Quarry::Design.spec "Example Specification" do
+    Example Specification
+    =====================
+    Shows that the number 5 does not equal 4.
 
-      i_will_show "concerning the number 5" do
+        5.assert! == 4
 
-        that "5 != 4" do
-          5.assert! == 4
-        end
+    But in fact equals 5.
 
-        but_that "5 == 5" do
-          5.assert == 5
-        end
+        5.assert == 5
 
-     end
+    QED.
 
-    end
+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.
 
-If you were to run this specification, you would simply see an outline.
+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
+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.)
 
-    = Example Specification
-    == i_will_show concerning the number 5
-    === that 5 != 4
-    === but_that 5 == 5
+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.
 
-If there were errors, we say *-items detaling each.
 
+=== Stubs
 
+Quarry provides a flexible stubbing facility.
+
+For now see RDoc API.
+
+
 === MethodProbe
 
-MethodProbe (aka the Duck Hunter) is an expiremental project --
-not meant for production use, that can dip-down into a method 
-and provide a read-out of the methods it uses. Thus it
-provides a (duck-)signiture of a method. Keep in mind, that
-becuase it is runtime bound it is not perfect. It can miss
-some parts of a method due to conditionals and, albiet rare,
-it can get stung by the halting problem.
+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
+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,
+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 Tiger Ops / Thomas Sawyer
+Copyright (c) 2007, 2008 Tiger Ops / Thomas Sawyer
 
 Quarry is distributed under the terms of the GPLv3.