Merge pull request #83 from TheTeaNerd/dk-explain-watchr-in-README

Explain Watchr use in README

.gitignore

@@ -1,5 +1,6 @@
 dist
 .project_env.rc
 .path_progress
+.rvmrc
 *.rbc
 koans/*

README.rdoc

@@ -2,15 +2,15 @@
 
 The Ruby Koans walk you along the path to enlightenment in order to learn Ruby.
 The goal is to learn the Ruby language, syntax, structure, and some common
-functions and libraries. We also teach you culture. Testing is not just something we
+functions and libraries. We also teach you culture by basing the koans on tests.
-pay lip service to, but something we live.  It is essential in your quest to learn
+Testing is not just something we pay lip service to, but something we
-and do great things in the language.
+live.  Testing is essential in your quest to learn and do great things in Ruby.
 
 == The Structure
 
-The koans are broken out into areas by file, hashes are covered in about_hashes.rb,
+The koans are broken out into areas by file, hashes are covered in +about_hashes.rb+,
-modules are introduced in about_modules.rb, etc.  They are presented in order in the
+modules are introduced in +about_modules.rb+, <em>etc</em>.  They are presented in
-path_to_enlightenment.rb file.
+order in the +path_to_enlightenment.rb+ file.
 
 Each koan builds up your knowledge of Ruby and builds upon itself. It will stop at
 the first place you need to correct.
@@ -23,23 +23,23 @@ make it work correctly.
 == Installing Ruby
 
 If you do not have Ruby setup, please visit http://ruby-lang.org/en/downloads/ for
-operating specific instructions.  In order to run this you need ruby and rake
+operating specific instructions.  In order to run the koans you need +ruby+ and
-installed. To check the installations simply type:
++rake+ installed. To check your installations simply type:
 
 *nix platforms from any terminal window:
 
    [~] $ ruby --version
    [~] $ rake --version
 
-Windows from the command prompt (cmd.exe)
+Windows from the command prompt (+cmd.exe+)
 
    c:\ruby --version
    c:\rake --version
 
-If you don't have rake installed, just run `gem install rake`
+If you don't have +rake+ installed, just run +gem install rake+
 
 Any response for Ruby with a version number greater than 1.8 is fine (should be
-around 1.8.6 or more). Any version of rake will do.
+around 1.8.6 or more). Any version of +rake+ will do.
 
 == Generating the Koans
 
@@ -54,10 +54,10 @@ If you need to regenerate the koans, thus wiping your current `koans`,
 
 == The Path To Enlightenment
 
-You can run the tests through rake or by calling the file itself (rake is the
+You can run the tests through +rake+ or by calling the file itself (+rake+ is the
 recommended way to run them as we might build more functionality into this task).
 
-*nix platforms, from the koans directory
+*nix platforms, from the +ruby_koans+ directory
 
     [ruby_koans] $ rake                           # runs the default target :walk_the_path
     [ruby_koans] $ ruby path_to_enlightenment.rb  # simply call the file directly
@@ -69,14 +69,16 @@ Windows is the same thing
 
 === Red, Green, Refactor
 
-In test-driven development the mantra has always been, red, green, refactor.  Write a
+In test-driven development the mantra has always been <em>red, green, refactor</em>.
-failing test and run it (red), make the test pass (green), then refactor it (that is
+Write a failing test and run it (<em>red</em>), make the test pass (<em>green</em>),
-look at the code and see if you can make it any better).  In this case you will need
+then look at the code and consider if you can make it any better (<em>refactor</em>).
-to run the koan and see it fail (red), make the test pass (green), then take a
-moment and reflect upon the test to see what it is teaching you and improve the
-code to better communicate its intent (refactor).
 
-The very first time you run it you will see the following output:
+While walking the path to Ruby enlightenment you will need to run the koan and
+see it fail (<em>red</em>), make the test pass (<em>green</em>), then take a moment
+and reflect upon the test to see what it is teaching you and improve the code to
+better communicate its intent (<em>refactor</em>).
+
+The very first time you run the koans you will see the following output:
 
     [ ruby_koans ] $ rake
     (in /Users/person/dev/ruby_koans)
@@ -98,7 +100,7 @@ The very first time you run it you will see the following output:
     mountains are merely mountains
     your path thus far [X_________________________________________________] 0/280
 
-You have come to your first stage. If you notice it is telling you where to look for
+You have come to your first stage. Notice it is telling you where to look for
 the first solution:
 
     Please meditate on the following code:
@@ -106,22 +108,49 @@ the first solution:
     path_to_enlightenment.rb:38:in `each_with_index'
     path_to_enlightenment.rb:38
 
-We then open up the about_asserts.rb file and look at the first test:
+Open the +about_asserts.rb+ file and look at the first test:
 
     # We shall contemplate truth by testing reality, via asserts.
     def test_assert_truth
       assert false                # This should be true
     end
 
-We then change the +false+ to +true+ and run the test again.  After you are
+Change the +false+ to +true+ and re-run the test.  After you are
 done, think about what you are learning.  In this case, ignore everything except
 the method name (+test_assert_truth+) and the parts inside the method (everything
 before the +end+).
 
 In this case the goal is for you to see that if you pass a value to the +assert+
-method, it will either ensure it is +true+ and continue on, or fail if in fact
+method, it will either ensure it is +true+ and continue on, or fail if
 the statement is +false+.
 
+=== Running the Koans automatically
+
+<em>This section is optional.</em>
+
+Normally the path to enlightenment looks like this:
+
+    cd ruby_koans
+    rake
+    # edit
+    rake
+    # edit
+    rake
+    # etc
+
+If you prefer, you can keep the koans running in the background so that after you
+make a change in your editor, the koans will immediately run again. This will
+hopefully keep your focus on learning Ruby instead of on the command line.
+
+Install the Ruby gem (library) called +watchr+ and then ask it to
+"watch" the koans for changes:
+
+    cd ruby_koans
+    rake
+    # decide to run rake automatically from now on as you edit
+    gem install watchr
+    watchr ./koans/koans.watchr
+
 == Inspiration
 
 A special thanks to Mike Clark and Ara Howard for inspiring this