Improve documentation.

README.md

@@ -102,17 +102,18 @@ Resources and Providers
 Running examples
 ----------------
 
-To try the examples, you should setup a test machine running Ubuntu 10.04 that will run the code. Either name the machine `client` in your `/etc/hosts`, or rename `nodes/client.json` so that `client` is actual name.
+To run the examples, you should setup a test machine running Ubuntu 10.04 that will run the code. Either name the machine `client` in your `/etc/hosts`, or rename `nodes/client.json` so that `client` is actual name.
 
 Checkout this repository and go into it:
 
+    git clone git://github.com/igal/antipackaging.git
     cd antipackaging
 
-Install pocketknife, if you don't already have it -- you may need to use `sudo`:
+Install pocketknife, you may need to use `sudo`:
 
     gem install pocketknife
 
-The following commands will apply changes to `client`. The first time you use these, you may be asked to install Chef on the client, agree to this or install it yourself. Because these download and compile code, they make take some time.
+The following commands will apply changes to `client`. The first time you use these, you may be asked to install Chef on the client, agree to this or install it yourself. Because these download and compile code, they may take a few minutes.
 
 Apply the `standalone` recipe to install `nginx`:
 

cookbooks/antipackaging/recipes/stow.rb

@@ -1,19 +1,22 @@
+# Same as `standalone.rb` recipe, but now using a custom resource.
 stow_package "nginx" do
   version "1.3.1"
   check "sbin/nginx"
   url "https://s3.amazonaws.com/igalfiles/#{@name}-#{@version}.tar.gz"
   install "./configure --prefix=@@PREFIX@@ && make && make install"
-  ### Same thing using a Ruby lambda:
+  ### Same as above using a Ruby lambda:
   # install lambda { |prefix| "./configure --prefix=#{prefix} && make && make install" }
   dependencies %w[build-essential libpcre3-dev]
 end
 
+# Same resource, but for different software with a trickier installation.
 stow_package "ts" do
   version "0.7.3"
   check "bin/ts"
   url "https://s3.amazonaws.com/igalfiles/#{@name}-#{@version}.tar.gz"
+  # Software doesn't use `./configure`, so use Ruby to escape `prefix` path and use `sed` to alter `Makefile`:
   install lambda { |prefix| "sed -i 's/^PREFIX\?=\\/usr\\/local$/PREFIX?=#{prefix.gsub(/\//, '\\/')}/' Makefile && make && make install" }
-  ### Same thing using a fancy, newfangled sed that allows custom search delimiters:
+  ### Same as above using a fancy, newfangled sed that allows custom search delimiters:
   # install lambda { |prefix| "sed -i 's|^PREFIX\?=\/usr\/local$|PREFIX?=#{prefix}|' Makefile && make && make install" }
   dependencies %w[build-essential]
 end