%#--
%# 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'

<%
  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',
    'minitest'      => 'http://blog.zenspider.com/minitest',
    'Context'       => 'http://github.com/jeremymcanally/context',
    'Shoulda'       => 'http://thoughtbot.com/projects/shoulda',
    'Bacon'         => 'http://chneukirchen.org/repos/bacon/README',
    'test-spec'     => 'http://test-spec.rubyforge.org/test-spec',
    'RSpec'         => 'http://rspec.info',
    'Test::Unit'    => 'http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/index.html',
  }

  def related_works.link_for key
    if val = self[key]
      "[#{key}](#{val})"
    else
      raise key
    end
  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.
    * Its core consists of a mere <%= `sloccount lib/dfect.rb`[/^\d+/] %> lines of code.


  %|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.

    Other testing libraries do not fulfill this need.  Instead, they simply report each failed assertion along with a stack trace (if I am lucky) and abruptly terminate my program.

    This deliberate separation of *fault* (my program being in an erroneous state) and *cause* (the source code of my program which caused the fault) reduces me to a primitive and laborious investigative technique known as "[printf debugging](http://oopweb.com/CPP/Documents/DebugCPP/Volume/techniques.html#PRINTF)".

    If you are not the least bit *unsettled* by those two words, then recall your first encounter with [IRB, the interactive Ruby shell](http://tryruby.hobix.com/):  remember how you would enter code expressions and IRB would *instantly* evaluate them and show you the result?

    What an immense productivity boost!  A *stark contrast* to the endless toil of wrapping every such experiment in standard boilerplate (`public static void`...), saving the result to a correctly named file, invoking the C/C++/Java compiler, and finally executing the binary---only to be greeted by a [segfault](http://en.wikipedia.org/wiki/Segmentation_fault). ;-)

    I exaggerate, for the sake of entertainment, of course.  But my point is that the Ruby testing libraries of today have (thus far) limited our productivity by orphaning us from the nurturing environment of IRB and shooing us off to a barren desert of antiquated techniques.  How cruel!

    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 "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"
    from users like you:

    %< "../CREDITS"


  %|section "Related works"

    %|related_works.keys.sort_by {|name| name.downcase }.each do |name|
      * <%= related_works.link_for name %>