quarry 0.3.0

data/METADATA

@@ -0,0 +1,22 @@
+---
+project   : quarry
+version   : 0.3.0
+status    : beta
+
+title     : Quarry
+subtitle  : Ruby Development Libraries
+slogan    : ALL YOUR BASE ARE BELONG TO RUBY!
+created   : 2006-12-16
+
+
+abstract  :
+  Quarry is a small collection of libraries to facilitate
+  Ruby project development, testing and debugging.
+
+copyright : (c) 2007 Tiger Ops & 7rans
+
+author    : Thomas Sawyer <transfire@gmail.com>
+#email    : facets-universal@rubyforge.org
+homepage  : 'http://quarry.rubyforge.org'
+download  : 'http://rubyforge.org/projects/quarry'
+

data/NEWS

@@ -0,0 +1,8 @@
+= News & Release Notes
+
+== 0.3.0 // 2008-08-18
+
+This is the first release of quarry. It is still
+quite betaware, however the BDD specification
+system is in a usable state.
+

data/README

@@ -0,0 +1,75 @@
+= Ruby Quarry
+
+  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.
+
+
+== Features
+
+=== Design::Specification
+
+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.
+
+    require 'quarry/assertion'
+
+    4.assert = 5
+
+This will raise ans Assertion error. Quarry's design specification
+then is just a measn of outlining and capturing these
+assertions.
+
+The sepcification themeleleves are completely freewform. There is
+no enforced nomenclature. Eg.
+
+    Quarry::Design.spec "Example Specification" do
+
+      i_will_show "concerning the number 5" do
+
+        that "5 != 4" do
+          5.assert! == 4
+        end
+
+        but_that "5 == 5" do
+          5.assert == 5
+        end
+
+     end
+
+    end
+
+If you were to run this specification, you would simply see an outline.
+
+    = Example Specification
+    == i_will_show concerning the number 5
+    === that 5 != 4
+    === but_that 5 == 5
+
+If there were errors, we say *-items detaling each.
+
+
+=== 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.
+
+
+== Copying
+
+Copyright (c) 2007 Tiger Ops / Thomas Sawyer
+
+Quarry is distributed under the terms of the GPLv3.
+
+

data/VERSION

@@ -0,0 +1 @@
+quarry 0.3.0 beta 2008-08-21

data/bin/rubybreak

@@ -0,0 +1,3 @@
+#! /usr/bin/ruby1.8
+
+require 'ratchets/test/break'

data/bin/xact-ruby

@@ -0,0 +1,6 @@
+#! /usr/bin/ruby
+
+load 'rivets/commands/xacto-ruby.rb'
+
+Rivets::Xact::RubyCommand.run
+

data/demo/spec/demo_check.rb

@@ -0,0 +1,21 @@
+require 'quarry/test/spec'
+
+Quarry::Design.specification "Example Specification" do
+
+  demonstrate "basic assertions" do
+
+    notice_that "4 != 3" do
+      4.must == 3
+    end
+
+    and_that "4.must_not == 4 is false" do
+      4.must_not == 4
+    end
+
+    as_well_as_that "raise ArgumentError does not raise a SyntaxError" do
+      lambda{raise ArgumentError}.must.raise? SyntaxError
+    end
+
+  end
+
+end

data/demo/spec/demo_outline.rb

@@ -0,0 +1,25 @@
+require 'ratchets/spec/design'
+
+Ratchets::Design.specification "Example Specification" do
+
+  demonstrate "basic assertions" do
+
+    that "4.must == 3 fails" do
+      4.must == 3
+    end
+
+    that "4.must_not == 4 fails" do
+      4.must_not == 4
+    end
+
+    that "raise ArgumentError does not raise a SyntaxError" do
+      lambda{raise ArgumentError}.must.raise? SyntaxError
+    end
+
+  end
+
+end
+
+$no_autocheck = true
+
+Ratchets::Design.outline

data/demo/test/demo_run.rb

@@ -0,0 +1,21 @@
+require 'ratchets/test/case'
+
+Ratchets::Test.suite "example suite" do
+
+  test_case "example case" do
+
+    test "4 should equal 3" do
+      4.assert == 3
+    end
+
+    test "4 should not equal 4" do
+      4.assert_not == 4
+    end
+
+    test "raises syntax error" do
+      lambda{raise SyntaxError}.should.raise? SyntaxError
+    end
+
+  end
+
+end

data/doc/manual.html2

@@ -0,0 +1,1416 @@
+<HTML>
+
+<HEAD>
+
+  <TITLE>Ratchets - User Manual</TITLE>
+
+  <LINK REL="SHORTCUT ICON" HREF="img/ruby.gif"/>
+  <LINK REL="StyleSheet" HREF="style.css" TITLE="Times" TYPE="text/css">
+
+  <SCRIPT language="javascript" src="js/jquery.js"></script>
+
+  <SCRIPT type="text/javascript">
+    var chapter_count = 0;
+
+    function chapter(name) {
+      chapter_count++;
+      document.write('<h1 id="ch' + chapter_count + '">' + chapter_count + '. ' + name + '</h1>');
+      $('#table_of_contents').append('<li><a href="#ch' + chapter_count + '">' + name + '</a></li>');
+    };
+
+    var view_mode = false;
+
+    function toc_toggle() {
+      if(view_mode) {
+        $('#text').css('margin-left','260px');
+        $('#toc').show();
+        view_mode = false;
+      } else {
+        $('#toc').hide();
+        $('#text').css('margin-left','20px');
+        view_mode = true;
+      };
+    };
+  </SCRIPT>
+
+</HEAD>
+<BODY>
+
+<div id="toggle" style="position: fixed; top: 0; left: 0;">
+  <a href="javascript: toc_toggle();"><img src="img/icon/book.jpg" height="30px;" style="border: none;"/></a>
+</div>
+
+
+<!-- Side Table of Contents -->
+
+<div id="toc">
+  <img src="img/icon/book.jpg" align="left" style="padding-right: 10px;"/>
+  <h1>Ratchets</h1>
+  <h2>User Manual</h2><br/>
+  <b>Table of Contents</b>
+  <ol id="table_of_contents"></ol>
+  <div id="copy">Copyright &copy; 2006 Thomas Sawyer.<br/>All Rights Reserved.</div>
+</div>
+
+
+
+<div id="text">
+
+<!-- Title -->
+
+<div id="booktitle" style="text-align: left;">
+  <div id="title1">RATCHETS</div>
+  <div id="title2">User Manual</div>
+  <br/>
+  <div>&nbsp;rev. <span id="rev">9</span> (~<span id="rev">75%</span>) </div>
+</div>
+
+<div id="copy">Copyright &copy; 2006 Thomas Sawyer. All Rights Reserved.</div>
+
+
+<!-- Introduction -->
+
+<div id="intro" class="section" style="margin-top: 40px;">
+
+<div class="part">Introduction</div>
+
+
+<script type="text/javascript"> chapter('Introducing Ratchets'); </script>
+
+<p>Ratchets started life as <i>Reap</i>, a project assistant application born of a complex Rakefile.
+Rake is the most widely used task tool for Ruby, but over time, small implementations details led
+Reap to become it's own independent build system. Reap was a great tool, but it was still very much
+a work in progress... a program in search of it's source.</p>
+
+<p>Then one day, while working on Ratchets' sister project <a href="http://facets.rubyforge.org">Facets</a>
+inspiration struck. The key to the "new Reap" is the same as Facets. Just as Facets is a collection of
+programming tools, so too the "new Reap" would be a collection of project tools. These tools could
+be called upon by any program, including utilities Ratcehts would provide, but first and foremost
+it would be a library. And thus Ratchets was born.</p>
+
+<p>Ratchet's features:</p>
+
+<ul>
+<li>Reuable collection of project management tools.</li>
+<li>Tools can get settings from a central project information store.</li>
+<li>Tools are accessable via a command-line utility.</li>
+<li>Promotes convention over configuration, but still remains flexible.</li>
+</ul>
+
+<div class="special"><b>IMPORTANT!</b> This documentation is not yet complete. If you look at the
+header at the top of the page, you will see a rev. number. Beside the rev. number is an approx. 
+percentage of completion. Keep that in figure in mind as you read through the documentation.
+Thanks.</div>
+
+
+<script type="text/javascript"> chapter('Getting Started'); </script>
+
+<p>If you haven't already done so, you'll first need to install Ratchets.
+The process is straight-forward. Download the package file, decompress it,
+'cd' into the package directory and run <code>setup.rb</code>. Eg.</p>
+
+  <pre>
+    $ tar -xvzf ratchets-0.7.0.gzip
+    $ cd ratchets-0.7.0
+    $ sudo ruby setup.rb
+  </pre>
+
+<p>Alternatively you can install the gem.</p>
+
+  <pre>
+    $ gem install ratchets
+  </pre>
+
+<p>Once installed you can immediately start using Ratchets. Here's the down low.</p>
+
+<p>Rathcets has a command line tool called, simply enough, <code>project</code>.
+While there are a few other commands you'll eventually want to know about, this
+is the main facility. You can use <code>project --help</code> to familiarize yourself
+with some of it's capability.</p>
+
+<p>In general the first argument given to <code>project</code> is either the name
+of a built-in tool or the name of a user-defined task, followed by any extra
+information to effect the results of the script/task.</p>
+
+<!--
+TODO!!!!
+<p>While you can use the project command as a fully independent command,
+a <i>ProjectInfo</i> file ...
+</p>
+-->
+
+</div>
+
+
+<!-- Project Generation -->
+
+<div id="proj" class="section">
+
+<img src="img/radio_earth.jpg" align="right" style="padding: 0 10px;"/>
+
+<div class="part">Part I</div>  <div id="title1" style="color: #44ee33;">Project Generation</div>
+
+
+<script type="text/javascript"> chapter('Creating a New Project'); </script>
+
+<p>As mentioned at the end of the previous chapter, Ratchets is utilized primarily through
+the <code>project</code> command-line interface. By supplying this command the name of a
+"ratchet" with subsequent options we activate various build procedures.</p>
+
+<p>The first "ratchet" we will cover, as it is likely the first anyone will need,
+is <code>new</code>. The new tool is be used to generate new project scaffolding
+or add additional <i>parts</i> to an existing project.</p>
+
+<p>Let look at creating a whole new project. To do this, first create a directory for the
+new project, <code>cd</code> into it, then invoke <code>project new</code>.</p>
+
+  <pre>
+    $ mkdir myproject
+    $ cd myproject
+    $ project new
+    Project ready.
+  </pre>
+
+<p>And just like that, a standard Ruby project layout is created. If you look at the contents of the directory
+you will see conventional folders like <code>bin/ lib/</code> and <code>data/</code>. The conventions
+followed are according to those established by Minero Akoi's
+<a href="http://i.loveruby.net/en/projects/setup/doc/">setup.rb</a>. If you are relatively new to Ruby
+it is a good idea to familiarize yourself with this material.</p>
+
+<p>Besides the standard layout, <code>new</code> can also create a subversion layout which includes
+the associated <code>branches  tags  trunk</code> tier. Simply specify the option as <code>--svn</code>
+or <code>--subversion</code> after <code>new</code>.
+
+  <pre>
+    $ project new --svn
+  </pre>
+
+<p>With or without the subversion tier, <code>new</code> also has a website layout option,
+<code>--web</code>, which will create an additional tier with an <code>index.html</code> file and
+some other website related structure, placing the source repository in a <code>src</code> subdirectory.
+This is a great way to layout a project, btw.</p>
+
+<p>The <code>new</code> command can create even better project scaffolding if we first provide
+some information about our project. To do that we must first create a <i>project information file</i>.
+The information in this file can then be used by Ratchets to enhance the new project's scaffolding.</p>
+
+  <pre>
+    $ mkdir myproject
+    $ cd myproject
+    $ project new --info
+    CREATED: ProjectInfo
+    Please edit the file to suit your project.
+  </pre>
+
+<p>As you can see this creates a <i>project information file</i> called <code>ProjectInfo</code>.
+Another, and perhaps better way to create a ProjectInfo file is to copy one from some
+other project and modify it to suit your needs. That makes it easier to learn how to fill
+them out. But if you don't have that option or you are already familiar with the layout,
+then you can use the <code>new</code> command create a blank template.</p>
+
+<p>The name of the project information file has some flexibility. Capitalization, for
+instance, is insignifficant; <code>projectinfo</code> would do just as well. Also
+a few alternative namings are supported, namely, <code>project.yaml</code> or just
+<code>PROJECT</code> (again capitalization doesn't matter). For simplicity sake we will refer
+to this file as the ProjectInfo file throughout the documentation. Just remember that you
+can substitue any of these other supported names in it's place to suit your personal preference.
+If you prefer one of the alternate names when creating the file, you can specify it as
+a parameter of the <code>--info</code> option.</p>
+
+  <pre>
+    $ project new --info project.yaml
+  </pre>
+
+<p>Rather then 'ProjectInfo', the file will be called 'project.yaml'. Ratchets will let you know
+if you pick a name it does not recognize.</p>
+
+<p>Once you have edited the ProjectInfo file (more on this in the next section), subsequnelty running
+<code>project new</code> will create the same project layout as before, but it will add
+enhanced details to further ease the creation of the new project. For instance, the lib
+directory will already have subdirectory named appropriately and if you use the --web option,
+the index.html page will be suitably labeled. And so on.</p>
+
+<div class="special"><b>NOTE</b> The enhanced information scaffolding is barely
+implemented as of yet. But will continue to improve with future releases.</div>
+
+<p>Of course, if you already have a project with which you wish to use Ratchets, rather than
+create a whole new project layout you will probably just want to add the <code><i>ProjectInfo</i></code>
+file to it. In that case you simply run <code>project new --info</code>. The project information file
+will be added and the rest of your project will be undisturbed. Running <code>project new</code> on
+a pre-existing project will have no effect. It will simply report an error that your project
+already has content.</p>
+
+<div class="special"><b>IMPORTANT!</b> Currently there is a small
+problem with automatic scaffolding. If you are using an <code>svn</code> and/or a <code>web</code>
+project layout be sure to add <code>basedir: src</code>, <code>basedir: trunk</code> or
+<code>basedir: src/trunk</code> to the project information file depending on which combination
+of layout you are using. Or opionally you can move the project information file to the source
+directory and utilize it from there rather than the top-most tier. We will fix this issue in a
+future release.</div>
+
+<p>The project file is of central importance to Ratchets and the <code>project</code> command.
+The file is a YAML-formatted file storing shared information from which Ratchets' tools gather
+default information on how to perform their actions. Most subsequent activity will largely
+depend on the content of this file. So lets now turn our attention squarely to it.</p>
+
+
+<script type="text/javascript"> chapter('The ProjectInfo File'); </script>
+
+<p>The structure of the ProjectInfo file is fairly self-explanitory. The header is devoted to
+common information. This is generally followed by deafult tool settings. And lastly
+a <i>tasks</i> section is used to define user tasks. Each task entry is a YAML map where the
+key represent the task name followed by a private type (!!) which identifies the tool
+it invokes. The next line begins the indented attributes the tool needs to do the job.
+To a detailed list of parameters each tool accepts have a look at the  RDoc API.</p>
+
+  <b>Example ProjectInfo File</b><br/>
+
+  <pre>
+    --- %YAML:1.0
+
+    title    : Reap
+    name     : reap
+
+    version  : 6.0.0
+    status   : 'beta'
+
+    author   : Thomas Sawyer
+    created  : '2004-04-01'
+    email    : transfirz@zmail.com
+    homepage : "http://reap.rubyforge.org"
+
+    summary  : A Ruby Project Management Assistant
+
+    description: >
+      Reap comprises a set of tasks commonly needed by
+      Ruby package developers/deployers, such as testing,
+      packaging, releasing, etc. You can also use Reap
+      to create your own custom tasks. Reap utilizes a
+      YAML configuration file to harvest common project
+      information, significantly simplifying these chores.
+
+    rubyforge:
+      project  : reap
+      username : transami
+
+    revision:
+      tool: darcs
+      exclude:
+        - doc/api
+
+    package:
+      executables : [ reap, rubytest ]
+      dependencies:
+        - [ facets, '> 1.5' ]
+      exclude:
+        - snip
+        - doc/api
+
+    tasks:
+
+      foo: !!ruby
+      script: |
+        puts "Foo it is!"
+
+  </pre>
+
+<p>As you can the top portion is fairly self-explainitory. After that we see entries related to
+specific Ratchet tools like package. This entry specifies default parameters to use for any
+subsequent call of the package tool. We will cover this in more detail in the 
+<a href="tool.html">Tool Utilization</a> documention.</p>
+
+<p>Following this is the tasks section with which we can
+define our own user-defined tasks. Typically these are specializtions of the buil-in tools,
+but as you can see by our "silly example" arbitary tasks can be written as well. We will
+cover this in more detail in the <a href="task.html">Task Management</a> documentation.</p>
+
+
+<script type="text/javascript"> chapter('Verifying Project Information'); </script>
+
+<p>When Ratchets searches for a ProjectInfo file it will move up the
+directory hierarchy from the current working directory until it finds a ProjectInfo file
+and will assume the location of that file is your project's source directory unless the file
+itself specifes that another directory is the source root.</p>
+
+<p>Project has one other subcommand that can be used to verify the project information: <code>info</code>.
+This simply dumps the parsed  contents of the ProjectInfo file to stdout.</p>
+
+  <pre>
+    $ project info
+  </pre>
+
+<p>This may seem trivial, but it can be sometimes be useful to quicky insure information
+is correct and that you are calling <code>project</code> from an appropriate location. [ed-
+the order of information is arbitrary, so it looks a bit messy. This will be improved
+in a future release.]</p>
+
+</div>
+
+
+<!-- Task Management -->
+
+<div id="task" class="section">
+
+<img src="img/clipboard2.png" align="right" style="margin-top: -75px; padding: 10px;"/>
+
+<div class="part">Part II</div>
+
+<div id="title1" style="color: #884444;">Task Management</div>
+
+
+<script type="text/javascript"> chapter('Task Versitility'); </script>
+
+<p>Ratchets is a very versitile application. Ratchets supports a number of techniques
+for utilizing it's built-in tools and defining new tasks. Depedending on the desired usage,
+Ratchets can be a build tool <i>library</i>, or taking advantage of it's own system, can
+be used as a build tool in its own right.</p>
+
+<p>One easily adopted usage of Ratchets is as a build library invoked from Rake.
+Rake is the prevalent build tool for Ruby, and an excellent one at that. Ratchets
+tools can be easily called from any application, so calling them from a Rake task
+is a natural endeavor. Ratchets goes a step further in its support of Rake however
+by allowing the built-in tools to be setup as Rake tasks automatically.
+If this is intended usage jump down to <a href="#ch4">Ratchets a la Rake</a>
+to learn more.</p>
+
+<p>On the other hand, forgoing a separate build tool, tasks can instead be defined
+as YAML descriptors and invoked via thae <code>project</code> command-line utility.
+This makes tasks extremely easy to read and write, and allows project information
+and task definitions to be jointly located but still universally accessible as
+pure data. We will cover this usage in <a href="#ch2">Describing Tasks
+via YAML</a>.</p>
+
+<p>The other alternative, which we will discuss last, is for tasks to be defined as
+stand-alone executables. This approach is in the spirit of Unix --it's favor of many
+small tools over single monolithic applications. Ratchets provides strong support
+for this mode of operation, which we have dubbed the <a href="#ch3">Sake Technique</a>.
+[ed- In fact, it is my prefered usage.]</p>
+
+<p>In any case, no matter which technique is used. The centralized data resource
+for project information is readily available. This <i>reapability</i> of
+information, probably more than any other feature, makes Ratchets so effective.</p>
+
+<div class="special">
+<b>SIDE NOTE</b> The terms <i>tool</i> and <i>task</i> are often used interchangably.
+Loosly speaking a tool is a built-in task, and a task is a user-defined tool.
+Furthermore, <i>tool</i> will generally be the term used when calling upon
+Ratchets as a library, whereas <i>task</i> is used when referring to an invocation
+of the Ratchets command-line utility <code>project</code>. In other words, these are
+rules of thumb and not hard distinctions.
+</div>
+
+
+<!--
+
+<p>The conversion is almost seemless. The task class needs only conform to some simple conventions (in this case
+for example you can see the package_file.include needs to be reduced to a single 'include' attribnute) which are farily
+trivial to implement. This format has been a big hit with Reap's users. Of course it's optional, one can still do
+everything through the Reapfile (but why?).</p>
+
+
+<h2>Sake may have some nice built-in tasks, but we use Rake. So what good is it?</h2>
+
+<p>Sake's unix style of many small scripts is fairly orthongonal to Rake's,
+So you can still call upon Sake's built-in scripts in your Rakefile, if you so prefer.
+Check it out:</p>
+
+  <pre>
+    require 'sake/project'
+
+    desc "Generate RDocs"
+
+    task :rdoc do
+      Automation.rdoc do |s|
+        s.template = 'jamis'
+        s.include = 'lib/**/*'
+      end
+    end
+  </pre>
+
+<p>Of course, you don't have to use Reap's task system. You can still use Rake's for all your project tasks if
+you prefer or for some reason must, and you can still get Reap's task functionality. Reap provides a simple interface
+for doing this. Here's an example of a Rakefile using Reap.</p>
+
+  <pre>
+    require 'reap/reap'
+
+    task_package 'pack' do |pkg|
+      pkg.distribute = [ 'gem' ]
+      pkg.dependencies = [ facets ]
+    end
+  </pre>
+
+<p>In the above, all information is provided directly via the Ruby task code. No information is coming from the
+projectinfo file (same is tru for a Reapfile). But you can also use Rake while utilizing the projectinfo file if
+you wish. In your Rakefile simple put:</p>
+
+  <pre>
+    require 'reap/rake'
+  </pre>
+
+<p>Then all the tasks defined in the projectinfo file will be available via Rake. You can still add additional
+Rake tasks, of course.</p>
+
+<p>Reap can be used in the same fashion as Rake. Simply create a Reapfile and use the <code>reap</code>
+command to utilize your tasks.</p>
+
+<p>Adding a extra Reap task is pretty easy. Just define a task in a the special <i>meta/reapfile</i>.
+If you have ever created a task in Rake's 'Rakefile' then you know how to do it here too. A simple
+task would look like this:</p>
+
+  <pre>
+    desc "My special task"
+    task :hello do
+      puts "Hello, World!"
+    end
+  </pre>
+
+<p>You may not like keeping a "monolithic" file of tasks and instead prefer to keep a collection of
+individual task scripts. You can do this by placing your script in the <i>meta/tasks</i> folder and
+encapsulating your task defintion in the Tasks module.</p>
+
+  <pre>
+    module Tasks
+
+      desc "My special task"
+      task :hello do
+        puts "Hello, World!"
+      end
+
+    end
+  </pre>
+
+-->
+
+
+<script type="text/javascript"> chapter('Describing Tasks with YAML'); </script>
+
+<!-- <h2 id="ch3">YAML Task Descriptors</h2> -->
+
+<p>You can define tasks using YAML <i>descriptors</i>. These can be placed directly in
+the ProjectInfo file unders a <code>tasks:</code> section. Or kept in a separate file 
+called <code>tasks</code>.</p>
+
+  <pre>
+
+    # Example tasks file
+
+    --- %YAML:1.0
+
+    package: !!package
+      distribute   : [ tar.bz2, gem, deb ]
+      dir: '../package'
+
+    release: !!release
+      host       : rubyforge.org
+      username   : transami
+      project    : reap
+      groupid    : 811
+      package    : Reap
+      dir        : '../DISTRIBUTION'
+
+    publish: !!publish
+      target   : rubyforge
+      type     : web
+      host     : rubyforge.org
+      username : transami
+      dir      : web
+
+    rdoc: !!rdoc
+      dir: 'web/doc/api'
+      main: README
+
+    announce: !!announce
+      to       : ruby-talk@ruby-lang.org
+      from     : &amp;email transfirz@zmail.com
+      domain   : unit.rubyforge.org
+      server   : smtp.gmail.com
+      port     : 587
+      account  : *email
+      type     : login  # cram_md5, plain
+      security : tls    # ~, tls, ssl (not working yet)
+      file     : doc/LATEST  # file contains announcement
+      slogan   : REAP THE REWARDS!
+      links    : []
+
+  </pre>
+
+<p>Once you tasks are defined you can see what tasks are ready to run simply by
+typing <code>project</code> without any arguments into the command line.
+For example you might see something like:</p>
+
+  <pre>
+    ~/myproj$ project
+    [from /home/foome/myprojects/foosys]
+      announce       Email project announcement.
+      doap           Generate DOAP project file.
+      extest         Extract unit-tests from script comments.
+      info           Display the ProjectInfo file.
+      install        Locally install package using setup.rb.
+      package        Build distribution packages.
+      publish        Publish documents to the web.
+      rdoc           Generate API Documentation.
+      release        Release distribution files.
+      test           Run unit-tests (each in a separate process).
+  </pre>
+
+<p>To run a task specifiy the name of the task to project, eg. <code>project announce</code>. 
+Task names take precedence over build script names.</p>
+
+
+<script type="text/javascript"> chapter('Ratchets a la Rake'); </script>
+
+<p>Using Ratchets via Rake is staright-forward, but can be approached in either of two ways.</p>
+
+<p>Since Ratchets' project tools are designed as stand-alone reusable modules, one can
+access them directly. For instance let's define an RDoc task by calling directly on
+Ratcehts' <code>Doc.rdoc</code> module method.</p>
+
+  <pre>
+    require 'ratchets/doc'
+
+    desc 'rdoc the project'
+
+    task :rdoc do
+      Ratchets::Doc.rdoc do |r|
+        r.title    = "MyApplication"
+        r.main     = "README"
+        r.template = "html"
+        r.options  = ["--all", "--inline-source"]
+        r.include  = ["lib/**/*", "bin/*", "[A-Z]*"]
+        r.basedir  = "src"
+        r.output   = "rdoc"
+      end
+    end
+  </pre>
+
+<p>This usage leaves everything up to the the Rake file. Although most of these fields have reasonable
+defaults. Nonetheless, no information is being provided to the tool via a project information file,
+becuase we are invoking Ratchet's underlying rdoc tool directly.</p>
+
+<p>Now let's do the same thing, but via the Project class.</p>
+
+  <pre>
+    require 'ratchets/project'
+
+    project = Project.new do |info|
+      info.title   = "MyApplication"
+      info.basedir = "src"
+    end
+
+
+    desc 'rdoc the project'
+
+    task :rdoc do
+      project.rdoc do |r|
+        r.main     = "README"
+        r.template = "html"
+        r.options  = ["--all", "--inline-source"]
+        r.include  = ["lib/**/*", "bin/*", "[A-Z]*"]
+        r.output   = "rdoc"
+      end
+    end
+  </pre>
+
+<p>Here we have created a new Project object and have invoked the rdoc tool <i>via</i> it's interface.
+This automatically incorporates general information about the project of use to the tool --in this case
+the project's title and it's basedir. The other fields are rdoc specific so they cannot be shared.
+But we can go a step further and define a set of <i>tool specific defaults</i> for any rdoc task.</p>
+
+  <pre>
+    require 'ratchets/project'
+
+    project = Project.new(
+      :title   => "MyApplication"
+      :basedir => "src"
+      :rdoc    => {
+        :main     => 'README'
+        :template => "html"
+        :options  => ["--all", "--inline-source"]
+        :include  => ["lib/**/*", "bin/*", "[A-Z]*"]
+        :output   => "rdoc"
+      }
+    )
+
+
+    desc 'rdoc the project'
+
+    task :rdoc do
+      project.rdoc
+    end
+  </pre>
+
+<p>You'll also notice that we are demonstrating Ratchet's versitility in accepting arguments.
+The <code>Project.new</code> method can take either a hash <u>or</u> a block. In fact, this is
+a widely used pattern throughout Ratchets.</p>
+
+<p>One final step. It's is likely we don't need to fuss with each and every tool Ratchets
+provides us. All-in-all we will probably want most, if not all, of them avaialble to us, and
+since Ratcehts generally provides reasonable defaults for most fields, we will rarely have
+to explicitly fill out each one. In fact, every field we gave thus far for rdoc, except
+title and basedir, are the default settings. So to facilitate this, the project class has an
+<code>autonew</code> method which automatically generates all the tasks for every project tool
+Ratchets offers.</p>
+
+  <pre>
+    require 'ratchets/project'
+
+    project = Project.autonew(
+      :title   => "MyApplication"
+      :basedir => "src"
+    )
+  </pre>
+
+<p>Now when you invoke <code>Rake -T</code> you will see a good sized list of available tasks.</p>
+
+<p>The techinque as discussed thus far is quite usable, and those heavily favoring pure Rake usage
+may wish to venture no further than right here. But there are is one final variation that has
+it's own benefits. Rather then store the project information as Ruby code within one's Rakefile,
+the information can be placed in a separate <i>ProjectInfo</i> file (something you are already
+familiar with if you read about Project Generation). To utilize this file, instead of using the
+<code>new</code> or <code>autonew</code> methods you instead use the <code>load</code> and
+<code>autoload</code> methods. The upshot is that your typical Rakefile may have little more
+than these two-lines:</p>
+
+  <pre>
+    require 'ratchets/project'
+    Project.autoload
+  </pre>
+
+
+<script type="text/javascript"> chapter('The "Sake" Technique'); </script>
+
+<p>Sake follows a non-centralized model of design. As such, Sake is essentially a collection of
+tools that make it easy to create your own sand-alone task scripts. Here's a basic example
+session of how such tasks are utilized.</p>
+
+  <pre>
+    $ cd sake/src
+
+    $ ls
+    bin     data  doc  ProjectInfo  setup.rb
+    _darcs  demo  lib  script       work
+
+    $ lt script/
+    [/home/monkey/code/ruby/sake/src]
+    script/package     # Generate distributable packages
+    script/version     # Generate VERSION file
+    script/release     # Release packages to hosting service
+    script/changelog   # Generate ChangeLog file
+    script/rdoc        # Generate API documentaiton
+
+    $ script/version -n
+    0.0.1 (2006-08-12)
+  </pre>
+
+<p>Notice the use of <code>lt</code>. That's an included utility that lists executable
+script in a given directory. It does this by grabbing the first comment line
+(that starts with #) it finds.</p>
+
+<br/>
+
+<p>Ruby task scripts are plan ruby scripts. The only thing special about them are:</p>
+
+    <ol><li>The bang header tells the system to run the script as a "rubytask"</li>
+        <li>The first comment line describes the task (mainly for use by <code>lt</code>).
+        <li>The name of the main method, if used, must be the same as the scripts (minus extension).
+    </ol>
+
+<p>Here's your obligatory <code>hello</code> example.</p>
+
+  <pre>
+    #! /usr/bin/env rubytask
+
+    # Hello World
+    #
+    # This is my first sake script!
+
+    puts "Hello, World!"
+  </pre>
+
+<p>How this example simply prints "Hello, World!" to stdout immediately. That may be fine one-off cases,
+but because it does not relegate the execution to a method however, it is not as easily reusable. A better
+way to write this example is:</p>
+
+  <pre>
+    #! /usr/bin/env rubytask
+
+    # Hello World
+    #
+    # This is my first sake script!
+
+    def hello
+      puts "Hello, World!"
+    end
+  </pre>
+
+<p>Keep in mind, for this to work, the file itself must be named 'hello' or 'hello.rb' 
+to match the main method's name.</p>
+
+<p>Ratcehts provides a convenient mechanism by which to call other stand-alone tasks
+simply by calling them as another method.</p>
+
+  <pre>
+    #!/usr/bin/env rubytask
+
+    # General preperation
+    #
+    # This script preforms a number of tasks to prepare for release.
+
+    testrun
+    changelog
+    version
+  </pre>
+
+<p>This will call three external scripts in order: test, changelog and version.
+Sometimes there is method is already defined with the same name as an external task. In those
+cases you can manually invoke the extrneal method via the <code>#rubytask</code> method.
+For instance the above can be also written:</p>
+
+  <pre>
+    #!/usr/bin/env rubytask
+
+    # General preperation
+    #
+    # This script preforms a number of tasks to prepare for release.
+
+    system_task 'testrun'
+    system_task 'changelog'
+    system_task 'version'
+  </pre>
+
+<p>The two forms are completely equivalent. The former is simply calling #system_task behined the scenes.</p>
+
+<p>The <code>rubytask</code> method restricts the same task from being run twice in the same execution session,
+so there's not need to worry about cascading task calls. On the other hand if you wish to reuse a task more
+than once, here's how to write a script to do so.</p>
+
+  <pre>
+    #!/usr/bin/env rubytask
+
+    require_local 'hello'
+
+    # Say hello three times
+
+    hello
+    hello
+    hello
+  </pre>
+
+<p>The "Sake" technique of creating tasks for a project takes a little more time to setup.
+But it has many distinct advantages. Among them:</p>
+
+<ul>
+<li>Tasks are clearly enumerable and can be viewed like any other file-system folder.</li>
+<li>Individual tasks can be quickly edited without having to sort through other task definitions.</li>
+<li>Permissions on tasks can be restricted individually.</li>
+<li>Shell-based tools can coexist along side rubytask tools.</li>
+</ul>
+
+
+<script type="text/javascript"> chapter('Lookup and Do'); </script>
+
+<p>What if I want to run a task script, but I'm currently way down in the
+project's directory tree. I dont want to <code>cd</code> all the way up or type
+<code>../</code> a bunch of times.</h2>
+
+<p>Sake provides a utility called <code>ludo</code> which stands for
+<i>lookup and do</i>. Just prepend that command to your invocation and it
+will find the executable and execute it.</p>
+
+  <pre>
+      % ludo script/info
+  </pre>
+
+<p>By the way, the <code>ludo</code> command can be used anywhere you like, it is
+not dependent on Sake to work. Albeit you should exercise some caution when doing
+so since <code>ludo</code> actively searches up the directory tree for a script 
+to execute.</p>
+
+
+<br/>
+
+<p>By the way, if you'd like to really make <i>sake</i> here's the process:</h2>
+
+  <div style="margin: 20px; margin-bottom: 50px;">
+    <img src="img/process.gif"/>
+  </div>
+
+<p>Good luck with that. <code>;)</code></p>
+
+</div>
+
+
+<!-- Build Tools -->
+
+<div id="tool" class="section">
+
+<img src="img/redratchet.jpg" align="right" style="margin-top: -30px; padding: 10px;"/>
+
+<div class="part">Part III</div>
+
+<div id="title1" style="color: #888844;">Tool Utilization</div>
+
+
+<script type="text/javascript"> chapter('Tools and the Project Class'); </script>
+
+<p>At it's core it is a set of integrated tools designed to simplify the life
+of Ruby application developers and project managers. The built-in tools cover
+the full range of common project needs, from setting up a standard project structure
+to packaging and making announcements. Because of commonality between the tools,
+Reap utilizes a central YAML configuration file(s) to harvest project information.
+This significantly simplifies usage.</p>
+
+
+<p>Custom tasks can also be easily created to suit specific project requirements.
+In this respect Reap is much like Rake.
+
+<p>Reap differentiates itself from the other build tools in a number of ways.
+It supports a variety of techinues for utilizing tools and defining tasks.
+Reap can be used as a Rake-clone. In fact Reap is a nearly 100% compatible
+replacement for Rake[1]. On the other hand, if you can't pull yourself
+away from Rake, Reap's tasks can also be used via Rake much like any other set of
+addon Rake tasks.</p>
+
+<p>Reap tasks can also be defined as standard executables, the ability to use YAML
+to easily setup built-in tasks, the use of a centralized data resource for project
+information and it's extensive library of built-in tasks. The built-in tasks are
+extensive enough that Sake can also be thought of as a complete project managment
+assitant application.</p>
+
+
+<script type="text/javascript"> chapter('Revision Tools'); </script>
+
+<p>Revision tools are tied to a particular revision control system like SVN or Darcs. The one exception is
+the backup tool which simply makes a raw compress backup of your source repository. Because of the
+tie into the particluar revision system you should make sure the <code>scm:</code> entry is set in your
+ProjectInfo file, otherwise these tools will not be be available. Vaild settings are <code>cvs</code>,
+<code>svn</code>, <code>git</code> and <code>darcs</darcs>.</p>
+
+<p><span class="red">IMPORTANT!</span> Only Darcs is fully supported at this time. The others will be supported
+in a future release.</p>
+
+<h2>Backup</h2>
+
+<p>Backup tool provides a facility to quuickly backup a project. The location of the backup will be under the given
+output folder, then under the name of the project and a subdirectory of the day’s date.
+For example, Ratchets itself was backed up to today at: <code>/var/backup/ratchets/ratchets_2006_10_21.tar.gz</code></p>
+
+  <pre class="list">
+  name        Name of project/backup
+  output      The backup directory (eg. '/var/backup')
+  folder      The directory to backup. [.]
+  </pre>
+
+<h2>History</h2>
+
+<p>The history tool produces a ChangeLog. The ChangeLog can be had in a number of styles.
+Presently <code>gnu</code> and <code>compact</code> are support. Both <code>xml</code> and 
+<code>yaml</code> formats will be available in an upcoming release.</p>
+
+  <pre class="list">
+  output      File to save the log. [doc/ChangeLog]
+  style       ChangeLog format. [gnu]
+  </pre>
+
+<h2>Stamp</h2>
+
+<p>The stamp tool produces a VERSION stamp. This is one-line string that gives
+version, release status and release date in a concise and readable, but machine parsable
+format.
+
+  <pre class="list">
+  version     Version of release.
+  status      Status of release (eg. beta, RC1).
+  released    Date of release.
+  file        File to save the version stamp.
+  </pre>
+
+
+<script type="text/javascript"> chapter('Progress Tools'); </script>
+
+<h2>Notes</h2>
+
+<p>The notes tool can lookup and list TODO, FIXME and other types of labeled comments from source code.</p>
+
+  <pre class="list">
+  include    File pattern selecting files to analyze.
+               Default pattern is 'lib/**/*'.
+  label      Types of notes to find [TODO, FIXME].
+  </pre>
+
+<h2>Stats</h2>
+
+<p>The stats tools provides file and LOC analysis of your code.</p>
+
+  <pre class="list">
+  include    The files to include in analysis.
+               Default pattern is 'lib/**/*'.
+  exclude    The files to exclude from analysis.
+  </pre>
+
+<h2>Test</h2>
+
+<p>Run unit-tests (each in a separate process).</p>
+
+<p>It will run unit tests. Each test file is run in a separate interpretor to prevent script clash.</p>
+
+<p>The Test class runs each test in it’s own proccess, making for a more pure test facility.
+This prevents potential conflicts between scripts.</p>
+
+  <pre class="list">
+  tests       Test files (eg. test/tc_**/*.rb)
+
+                Defaults to typcial selection.
+  libs        List of lookup directories to include in
+                load path. './lib' is always included.
+  live        Flag to quickly deactive use of local libs.
+                Test against installed files instead.
+  reqs        List of any files to pre-require.
+  </pre>
+
+<p>NOTE This works well enough but it is a tad delicate. It actually marshals test results across
+ stdout->stdin shell pipe. One consequence of this is that you can’t send debug info to stdout in 
+your tests #(including p and puts).</p>
+
+
+<script type="text/javascript"> chapter('Manifest Tools'); </script>
+
+<h2>Manifest</h2>
+
+<p>Manifest class produces a simple file manifest for a project, listing the path
+of each file and it’s MD5 checksum. 
+Create a manifest file for the package. By default is a very simple filename manifest.
+The check type can be supplied and a checksum will be given with each filename.
+In the future this will be exanded to build a varity of manifest formats.</p>
+
+  <pre class="list">
+   include       Files to include.
+   exclude       Files to exclude from the included.
+   file          Save the manifest to this file (otherwise stdout).
+   digest        Include optional digest type:
+                   md5, sha128 (sha1), sha256, sha512
+  </pre>
+
+<h2>Sign</h2>
+
+<p>Sign class will generate signitures for a library’s files. It also can generate
+a public key for the project if it does not have one. You must supply a private key.</p>
+
+  <pre class="list">
+  name       Project name.
+  keyfile    Pathname top .pem file of private key.
+  include    Glob of files to include.
+  exclude    Glob of files to exclude.
+  output     Dir to store signiture files [data/{name}/sig].
+  </pre>
+
+
+<script type="text/javascript"> chapter('Documentation Tools'); </script>
+
+<h2>Rdoc</h2>
+
+<p>RDoc tool is a user-friendly interface for generating RDocs via the rdoc shell command.
+This tool generates API documentation from source comments.</p>
+
+  <pre class="list">
+  title      Project title to use in documentation.
+  output     Directory to store documentation [doc]
+  source     Project location to document [.]
+  main       File to use as main page [README]
+  template   Which RDoc template to use [html]
+  include    Files to include in RDocs
+  exclude    Files to exclude from those
+  options    Pass-thru extra options to RDoc command
+  </pre>
+
+<h2>Publish</h2>
+
+<p>The publish tools provides a simple way to upload documents or even an entire
+website to a host.</p>
+
+  <pre class="list">
+  include    Files to include.
+  </pre>
+
+
+<script type="text/javascript"> chapter('Release Tools'); </script>
+
+<h2>Announce</h2>
+
+<p>The announce tool handles release announcements. It generates a nicely
+formated message and then emails to the specified address(es).</p>
+
+  <pre class="list">
+    title        Project title [title].
+    version      Project version [version].
+    summary      Brief one-line description [summary].
+    description  Long description of project [description].
+    homepage     Project homepage web address [homepage].
+    links        Array of http links to related sites.
+    file         File that contains announcement message.
+    memo         Embedded announcement message.
+    slogan       Motto for you project.
+    email        Send email otherwise just display announcement.
+  </pre>
+
+<p>If email is set to true, then these also apply:</p>
+
+  <pre class="list">
+    subject      Subject of email message.
+    from         Message FROM address [email].
+    to           Email address to send announcemnt.
+    server       Email server to route message.
+    port         Email server's port.
+    domain       Email server's domain name.
+    account      Email account name.
+    login        Login type: plain, cram_md5 or login.
+    secure       Uses TLS security, true or false?
+  </pre>
+
+<p>(Square brackets indicate defaults taken from Project information. if used via Project class.)</p>
+
+
+<h2>Package</h2>
+
+<p>Create distribution packages.
+
+<p>This tool can create standard .zip, .tgz, or .tbz packages, plus .gem, .deb and other distributions.</p>
+
+<p>Builds distribution packages. The package task supports tar.gz, tar.bz2, zip source packages
+and gem, pacman and debian ditribution packages.</p>
+
+  <pre class="list">
+Inherited settings:
+
+  name            Package name.
+  version         Package version.
+  architecture    Can be any, i368, i686, ppc, etc.
+  executables     Executable files in this distribution.
+
+Tool specific settings:
+
+  output          Directory in which to store distributions.
+  include         Files to include in distribution.
+  exclude         Files to exclude from those.
+  formats         List of distribution formats desired. Eg.
+                    tgz, tar.gz, tbz, tar.bz2, zip
+                    gem, deb, rpm, pac, etc.
+  tier            Version tier the package (for use with Library).
+  rules           Specify where files should go in package (see below).
+
+Seetings that can be of use depending on the package format.
+
+  category        Software category.
+  dependencies    List of packages this depends.
+  recommends      List of packages that can be used with this package.
+  replaces        List of packages this one replaces.
+
+RubyGems specific settings:
+
+  autorequire
+  platform
+  require_paths
+  </pre>
+
+<p>If you need to vary settings according to the format, all you need to do is create
+separate package tasks.</p>
+
+<p>There is one parameter that deserves additional attention. This is the setting called ‘rules’.
+The rules setting allows you to define how files are copied into the distribution package, so instead
+of a one to one copy of the included files, you can actually have a file placed in a different
+location within the distribution. This can be very handy if you wish to develop your project with one
+layout, but need to distribute it with another.</p>
+
+<p>See the Stage module for details on using rules.</p>
+
+
+<h2>Release</h2>
+
+<p>Upload release packages to hosting service.
+This task releases files to a host such as RubyForge.</p>
+
+    <pre class="list">
+    folder         Distribution directory
+    exclude        Distribution types to exclude
+    package        Package name
+    date           Date of release (defaults to Time.now)
+    processor      Processor/Architecture (Any, i386, PPC, etc.)
+    release        Release name (default is version number)
+    is_public      Public release?
+
+    changes        Changes given in string form.
+    notes          Release notes given in string form.
+             -or-
+    changelog      Change log file
+    notelog        Release notes file
+    </pre>
+
+<p>The release option can be a template by using %s in the string.
+The version number of your project will be sub’d in for the %s.
+This saves you from having to update the release name before every release.</p>
+
+
+<script type="text/javascript"> chapter('Deployment Tools'); </script>
+
+<h2>Setup</h2>
+
+<p>This tool builds and installs a project using setup.rb or install.rb.
+If neither exist setup.rb will be created for the purpose.</p>
+
+   <pre class="list">
+   options    Command line options to add to shell command.
+   </pre>
+
+
+<script type="text/javascript"> chapter('Creating Custom Tools'); </script>
+
+<p>Adding code to a rakefile or a sake-style script is fine for one-off tasks. But what if you
+need a more versitle and reusable tool --one you can add to your projectinfo file like Ratchets
+built-in tools? In that case you need to build a <i>custom tool</i>.</p>
+
+<p>If you have custom tools you'd like to use for all your projects you can place them
+either in you home directory under ~/.share/ratchets/tools/, or you could make them
+universally available to all users in the shared data directory, on Debian,
+/usr/share/ratchets/tools/. If, on the other hand, the tool is specific to a project,
+place it in a project tools/ folder.</p>
+
+<div class="special"><b>IMPORTANT!</b> While this is how you write a custom tool, the loading
+of custom tools is still on our TODO list. Sake-style scripts will have to suffice until
+we get this fixed.</div>
+
+<p>Here's a "simple" example of a custom tool:</p>
+
+  <pre>
+    # Add tool to a tool module (or add to an existing tool module).
+
+    module MyToolModule
+
+      module_function  # very important!
+
+      def simple( keys=nil, &amp;yld )
+        keys = (keys||yld).to_openobject
+
+        message = keys.message
+        signed  = keys.signed || '-annonymous'
+
+        puts message + "\n\n" + signed
+      end
+
+    end
+
+    # To use the new tool via project, add a tool interface.
+
+    class Project
+
+      tool :simple, 'my custom tool'
+
+      def simple( keys )
+        keys = keys.to_h
+        keys *= {
+          :message => info.message
+        }
+        keys *= (info[:simple] || {})
+        MyToolModule.simple(keys)
+      end
+
+    end
+  </pre>
+
+  <p>The corresponding settings in the ProjectInfo file can then be:</p>
+
+  <pre>
+     message: Hi, how are you?
+
+     tasks:
+
+       simple: !!simple
+         signed: Your friend, Tom.
+  </pre>
+
+  <p>And to use it type:</p>
+
+  <pre>
+     $ project simple
+  </pre>
+
+<p>Notice the reference to 'info'. This is an OpenStruct-like interface to the project information.</p>
+
+<p>It's a good idea to take some time and learn all the standard properties of a project's information file
+which you can draw on for your own tools. Looking at the RDoc API documentation will elucidate most of them.
+And, of course you can also invent your own if needed.</p>
+
+<p>The rest of building a tool is a matter or writing the code to have it do what you want. If you
+develop any nice tools, be sure to pass them along!
+</p>
+
+
+<script type="text/javascript"> chapter('Reaping the Rewards'); </script>
+
+<p>As you can see there are many tools...</p>
+
+</div>
+
+
+<!-- Test Services -->
+
+<div id="test" class="section">
+
+<img src="img/test.jpg" align="right" style="margin-top: -25px; padding: 10px;"/>
+
+<div class="part">Part IV</div>
+
+<div id="title1">Test Services</div>
+
+<br/><br/>
+
+<div style="color: white; width: 40%; font: bold 1.5em monospace; background: red; text-align: center;">
+  WARNING!!! TEST SERVICES ARE NOT READY FOR GENERAL USE!
+</div>
+
+
+<script type="text/javascript"> chapter('Summary of Test Services'); </script>
+
+<p>Ratchet's provides a number of different tools to help you
+test your applicaitons. Running units test was briefly covered
+in Tool Utilization, but Ratchets' test services are far more
+extensive. These include a full testing framework similar to
+Test Unit and RSpec, mock object classes to facilitate test
+creation, and a versitle breakpoint tool, as well as a variety
+of test run styles and modes.
+</p>
+
+
+<script type="text/javascript"> chapter('Unit Test Framework'); </script>
+
+<p>Ratchet's test framework is actually very simple in design. It is centered around a simple
+functor (ie. a function decorator) that routes all calls though an assertion hook. The functor
+is accessed the the <code>should</code> method, or it negating counterpart <code>should_not</code>.
+Via this special functor, we can use all of Ruby's typical commands to test assertions wihtout
+learning any special purpose DSL.</p>
+
+<p>Consider this simple example.</p>
+
+  <pre>
+    a = 1
+    a == 1
+    a.should == 1
+  </pre>
+
+<p>The difference between the 2nd and 3rd lines...</p>
+
+<p>Ratchets' Test Framework also support Behavior Driven Devlopment. BDD is primarily a 
+differnece in one's frame of mind rather the a substatially differnt meand of testing.
+But two method facilitate that minset: context and ???.</p>
+
+  <pre>
+    context "some context" do
+      ??? "some ???" do
+        a.should == 1
+      end
+    end
+  </pre>
+
+<p></p>
+
+
+<script type="text/javascript"> chapter('Making a Mockery'); </script>
+
+<p>Ratchets has a few mocking classes to make test writing easier. Mock objects
+are object that pretend to be other object. There is a generic mock object
+with versitle setup commands for creating complex mock interactions quickly and
+easily. There are also IO, File and Dir mock objects to avoid testing against
+fixtures. In the works is also an AOP-based wrapping mechinism that (with
+any luck) will make mocking pre-existing classes a snap.</p>
+
+
+<script type="text/javascript"> chapter('Breakpoints and Tracepoints'); </script>
+
+<p>Ratchets provides a couple of breakpoint tools. These can be 
+run externally or invoked by your code. Ratchets breakpoint system
+is quite versitle, based on the work Florian Gross' and Mentalurgy
+it can drop you into an irb seesion, or it can drop you into your
+favorite editor at the point of failure.</p>
+
+
+<script type="text/javascript"> chapter('Additional Testing Services'); </script>
+
+<p>Ratchets has a few additional testing tools that may be of use.</p>
+
+<p>The MethodProbe is an interesting tool that allows one to drop
+<i>decoy</i> arguments into a method and extract parameter interface
+requirements. Unfortunately MethodProbe is an imperfect device
+because Ruby does not expose all of it's features as overridable
+methods, in particular conditionals like <code>if</code> are not
+methods. So not all parameter interfaces can be determined.
+But with selective usage MehtodProbe can provide useful information.</p>
+
+
+<script type="text/javascript"> chapter('Excerpt Runner'); </script>
+
+<p>You may learn about Reap's ability to extract unit tests from source code wrapped in
+<code>=begin test...=end</code> comment blocks.</p>
+
+  <pre>
+    =begin test
+
+      require 'test/unit'
+
+      class TestThis &lt; Test::Unit::TestCase
+        assert_equal( 2, 1+1 )
+      end
+
+    =end
+  </pre>
+
+<p>This can be amazing convenient, especailly for testing functional support scripts. But it's not a
+convenient to have to extract your tests every time you need to run <i>one</i>. To solve this problem,
+Reap also includes a command called <code>rubytest</code>. To us it simply navigate to the file in
+question (eg. the one with the commented test, of course) and type:</p>
+
+  <pre>
+    % exrb myscript.rb
+  </pre>
+
+<p>And you'll see your standard test assertion feedback.</p>
+
+</div>
+
+
+<!-- Appendix -->
+
+<div id="appendix" class="section">
+
+<img src="img/appendix.png" align="right" style="margin-top: -25px; padding: 10px;"/>
+
+<div class="part">Appendix</div>
+
+
+<script type="text/javascript"> chapter('License'); </script>
+
+<p>
+Ratcehts<br/>
+Copyright &copy; 2006 Thomas Sawyer</br>
+</p>
+
+<p>Ruby/GPL License</p>
+
+<p>This program is free software; you can redistribute it and/or modify
+it under the terms of the Ruby License or GNU General Public License
+as published by the Free Software Foundation; either version 2 of the
+License, or (at your option) any later version.</p>
+
+<p>This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
+
+</div>
+
+</div>
+</body>
+</html>