dfect 1.0.0 → 1.1.0

data/doc/intro.erb

@@ -1,13 +1,14 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
 % api_url = './api/index.html'
 % src_url = 'http://github.com/sunaku/' + $program
 % git_url = 'http://git-scm.com'
+
 <%
-  competitors = {
+  related_works = {
     'assert{ 2.0 }' => 'http://assert2.rubyforge.org',
     'Verify'        => 'http://www.ruby-forum.com/topic/183354',
     'Testy'         => 'http://github.com/ahoward/testy/tree/master',
@@ -20,7 +21,7 @@
     'Test::Unit'    => 'http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/index.html',
   }
 
-  def competitors.link_for key
+  def related_works.link_for key
     if val = self[key]
       "[#{key}](#{val})"
     else
@@ -29,28 +30,33 @@
   end
 %>
 
+
 %|chapter "Introduction"
+
+
   %|project
+
     <%= $project %> is an assertion testing library for Ruby that emphasizes a simple assertion vocabulary, instant debuggability of failures, and flexibility in composing tests.
 
+
+  * <%= xref "History", "What's new?" %> --- history of project releases.
+  * [Source code](<%= src_url %>) --- obtain via [Git](<%= git_url %>) or browse online.
+  * [API reference](<%= api_url %>) --- documentation for source code.
+  * [Project home](<%= $website %>) --- the <%= $project %> project home page.
+
+  To get help or provide feedback, simply
+  <%= xref "License", "contact the author(s)" %>.
+
+
+  %|section "Features"
+
     <%= $project %> is exciting because:
     * It has only 5 methods to remember: D F E C T.
     * It lets you debug assertion failures interactively.
     * It keeps a detailed report of assertion failures.
     * It lets you nest tests and execution hooks.
-    * It is implemented in a mere <%= `sloccount lib`[/^\d+/] %> lines of code.
-
-  These features distinguish <%= $project %> from the competition:
-
-  %|competitors.keys.sort_by {|name| name.downcase }.each do |name|
-    * <%= competitors.link_for name %>
-
-  %|paragraph "Etymology"
-    <%= $project %> is named after the D F E C T methods it provides.
-
-    The name is also play on the word "defect", whereby the intentional misspelling of "defect" as "dfect" is a defect in itself!  <tt>;-)</tt>
+    * Its core consists of a mere <%= `sloccount lib/dfect.rb`[/^\d+/] %> lines of code.
 
-    This wordplay is similar to [Mnesia](http://www.erlang.org/doc/apps/mnesia/index.html)'s play on the word "amnesia", whereby the intentional omission of the letter "A" indicates forgetfulness---the key characteristic of having amnesia.  Clever!
 
   %|section "Motivation"
     The basic premise of <%= $project %> is that, when a failure occurs, I want to be put inside an interactive debugger where I have the freedom to properly scrutinize the state of my program and determine the root cause of the failure.
@@ -67,61 +73,32 @@
 
     And that, I say, is why <%= $project %> is essential to Ruby developers today.  It reunites us with our playful, interactive, *real-time* IRB roots and, with unwavering tenacity, enables us to investigate failures *productively*!
 
-  %|section "Logistics"
-    * <%= xref "History", "Release notes" %> --- history of project releases.
-    * [Source code](<%= src_url %>) --- obtain via [Git](<%= git_url %>) or browse online.
-    * [API reference](<%= api_url %>) --- documentation for source code.
-    * [Project home](<%= $website %>) --- the <%= $project %> project home page.
-
-    To get help or provide feedback, simply
-    <%= xref "License", "contact the author(s)" %>.
-
-    %|paragraph "Version numbers"
-      <%= $project %> releases are numbered in *major.minor.patch*
-      form according to the [RubyGems rational versioning
-      policy](http://www.rubygems.org/read/chapter/7), which
-      can be summarized thus:
-
-      <table markdown="1">
-        <thead>
-          <tr>
-            <td rowspan="2">What increased in the version number?</td>
-            <td colspan="3">The increase indicates that the release:</td>
-          </tr>
-          <tr>
-            <th>Is backward compatible?</th>
-            <th>Has new features?</th>
-            <th>Has bug fixes?</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <th>major</th>
-            <td style="background-color: #FFE4E1;">No</td>
-            <td>Yes</td>
-            <td>Yes</td>
-          </tr>
-          <tr>
-            <th>minor</th>
-            <td>Yes</td>
-            <td>Yes</td>
-            <td>Yes</td>
-          </tr>
-          <tr>
-            <th>patch</th>
-            <td>Yes</td>
-            <td style="background-color: #FFE4E1;">No</td>
-            <td>Yes</td>
-          </tr>
-        </tbody>
-      </table>
-
-    %|paragraph "License"
-      %< "../LICENSE"
+
+  %|section "Etymology"
+
+    <%= $project %> is named after the D F E C T methods it provides.
+
+    The name is also play on the word "defect", whereby the intentional misspelling of "defect" as "dfect" is a defect in itself!  <tt>;-)</tt>
+
+    This wordplay is similar to [Mnesia](http://www.erlang.org/doc/apps/mnesia/index.html)'s play on the word "amnesia", whereby the intentional omission of the letter "A" indicates forgetfulness---the key characteristic of having amnesia.  Clever!
+
+
+  %|section "License"
+
+    %< "../LICENSE"
+
 
   %|section "Credits"
+
     <%= $project %> is made possible by
-    <%= xref "History", "contributions" %>
+    %= xref "History", "contributions"
     from users like you:
 
     %< "../CREDITS"
+
+
+  %|section "Related works"
+
+    %|related_works.keys.sort_by {|name| name.downcase }.each do |name|
+      * <%= related_works.link_for name %>
+

data/doc/setup.erb

@@ -1,19 +1,51 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
+
 %|chapter "Setup"
+
+
   %|section "Requirements"
+
     Your system needs the following software to run <%= $project %>.
 
-    | Software                                          | Description               | Notes                                                                                  |
-    | --------                                          | -----------               | -----                                                                                  |
-    | [Ruby](http://ruby-lang.org)                      | Ruby language interpreter | Version 1.8.6, 1.8.7, and 1.9.1 have been tested successfully.                         |
-    | [RubyGems](http://rubygems.org)                   | Ruby packaging system     | Version 1.3.1 is required.                                                             |
-    | [ruby-debug](http://www.datanoise.com/ruby-debug) | Interactive debugger      | This is an _optional_ requirement;  IRB will be used if this library is not available. |
+    %|table
+      %|thead
+        %|tr
+          %|th
+            Software
+          %|th
+            Description
+          %|th
+            Notes
+      %|tbody
+        %|tr
+          %|td
+            [Ruby](http://ruby-lang.org)
+          %|td
+            Ruby language interpreter
+          %|td
+            Version 1.8.6, 1.8.7, and 1.9.1 have been tested successfully.
+        %|tr
+          %|td
+            [RubyGems](http://rubygems.org)
+          %|td
+            Ruby packaging system
+          %|td
+            Version 1.3.1 is or newer required.
+        %|tr
+          %|td
+            [ruby-debug](http://www.datanoise.com/ruby-debug)
+          %|td
+            Interactive debugger
+          %|td
+            **This requirement is optional.**  If this library is not available, then IRB (the standard interactive Ruby shell) will be used instead.
+
 
   %|section "Installation"
+
     You can install <%= $project %> by running this command:
 
         gem install <%= $program %>
@@ -21,3 +53,55 @@
     If you want to develop <%= $project %>, run this command:
 
         gem install <%= $program %> --development
+
+
+  %|section "Version numbers"
+
+    <%= $project %> releases are numbered in *major.minor.patch*
+    form according to the [RubyGems rational versioning
+    policy](http://www.rubygems.org/read/chapter/7), which
+    can be summarized as follows:
+
+    %|table
+      %|thead
+        %|tr
+          %|td :rowspan => 2
+            What increased in the version number?
+          %|td :colspan => 3
+            The increase indicates that the release:
+        %|tr
+          %|th
+            Is backward compatible?
+          %|th
+            Has new features?
+          %|th
+            Has bug fixes?
+      %|tbody
+        %|tr
+          %|th
+            major
+          %|td :style => "background-color: #FFE4E1;"
+            No
+          %|td
+            Yes
+          %|td
+            Yes
+        %|tr
+          %|th
+            minor
+          %|td
+            Yes
+          %|td
+            Yes
+          %|td
+            Yes
+        %|tr
+          %|th
+            patch
+          %|td
+            Yes
+          %|td :style => "background-color: #FFE4E1;"
+            No
+          %|td
+            Yes
+