headless doc updates

1 files changed, 57 insertions, 38 deletions

diff --git a/doc/manual_src/headlessFiveUI.md b/doc/manual_src/headlessFiveUI.md
index 9ed97b1..91a0b62 100644
--- a/doc/manual_src/headlessFiveUI.md
+++ b/doc/manual_src/headlessFiveUI.md
@@ -1,25 +1,25 @@
 % Automated testing with FiveUI
 
-# Introducing "headless"
+# Introducing "Headless"
 
 -------------
 
-The FiveUI distribution comes with a Java application called `headless` that is
+The FiveUI distribution comes with a Java application called `Headless` that is
 desiged to make automated testing with FiveUI easy.
 
-The headless tool can take a collection of FiveUI rule sets and a target (a
-single web page, an entire website, or a filtered part of one) and automate the
-running of FiveUI rules. Headless can output a text or HTML based report
-summarizing the run.
+Headless can take a collection of FiveUI rule sets and a target
+(a single web page, an entire website, or a filtered part of one)
+and automate running the rule sets on the target(s). Headless
+will then output a text or HTML based report summarizing the run.
 
 "Headless runs" are specified using text based run description files that are
 written in JSON format. The exact form of these descriptions is given below.
 Headless supports two modes for automating FiveUI. In the first mode,
-headless executes one FiveUI rule set per URL line in the run description and
-outputs a report indicating which rule sets passed or failed (and how) on each
-URL. In the second mode, headless uses each URL line to specify a seed from
+Headless executes one FiveUI rule set per URL line in the run description and
+outputs a report indicating which rule sets passed or failed (and how) for each
+URL. In the second mode, Headless uses each URL line to specify a seed from
 which a web crawl is started.  Parameters can be given to control the extent of
-the crawl
+the crawl.
 
 In what follows, `<FiveUI>` refers to the directory where you have installed the
 FiveUI distribution.
@@ -28,22 +28,35 @@ FiveUI distribution.
 
 -------------
 
-A "batteries included" jar file and helper script for using `headless`
-are included in the `<FiveUI>/bin` directory. To start using headless,
-first make sure you have a [Java runtime environment](http://www.java.com)
-and [Firefox](http://www.mozilla.org/en-US/firefox/new/) 17 (the
-E.S.R. release, see step 3 below) installed.
+### Install the dependencies
 
-### Go to the `<FiveUI>/bin` directory
+You will need the following dependenies installed on your system in order
+to use Headless. All of the dependencies can be found and easily installed
+on most major platforms (Linux, Mac OS X, Windows). The dependencies are:
+
+ - [Java runtime environment](http://www.java.com)
+ - [Firefox](http://www.mozilla.org/en-US/firefox/organizations/all.html) 17 (the
+   E.S.R. release)
+ - [Maven](http://maven.apache.org/download.cgi)
+ - an included Java library called `webdrivers` (see next step)
+
+Note that on some platforms (e.g. Mac OS X) the Java runtime and Maven are already
+pre-installed.
+
+### Install the included webdrivers dependency
+
+The following command will instruct Maven to install
+the webdrivers Java library to your local Maven repository.
 
 ```
-$ cd <FiveUI>/bin
+$ cd <FiveUI>/webdriver
+$ mvn install
 ```
 
 ### Edit the run script
 
-Edit variables at the start of `runHeadless.sh` to reflect your Firefox
-installation and FiveUI installation directory.
+Edit variables at the start of `<FiveUI>/bin/runHeadless.sh` to
+reflect your Firefox installation and FiveUI installation directory.
 
 ```
 $ cat runHeadless.sh
@@ -57,7 +70,7 @@ export FIREFOX_BIN_PATH=$HOME/myapps/Firefox17/Contents/MacOS/firefox
 The `runHeadless.sh` script can be invoked from the command line with options.
 
 ```
-$ runExample.sh -h
+$ runHeadless.sh -h
 usage: headless <input file 1> [<input file 2> ...]
  -h                      print this help message
  -o <outfile>            write output to file
@@ -66,7 +79,10 @@ usage: headless <input file 1> [<input file 2> ...]
  -vv                     VERY verbose output
 ```
 
-### Try running `runHeadless.sh` on one of the included run description files
+### Try one of the included example runs
+
+Here we execute the example headless run located in
+`<FiveUI>/exampleData/headlessRuns/basicRun.json`.
 
 ```
 $ cd <FiveUI>/exampleData/headlessRuns
@@ -80,24 +96,27 @@ com.galois.fiveui.BatchRunner  - skipping webcrawl
 com.galois.fiveui.BatchRunner  - building webdrivers ...
 com.galois.fiveui.BatchRunner  - built: [FirefoxDriver: firefox on MAC (acbc5ed2-2f3e-fc42-8d4d-08a3e31e30d6)]
 com.galois.fiveui.BatchRunner  - registering new webdriver...
-com.galois.fiveui.BatchRunner  - root path for webdriver is /Users/bjones/FiveUI/
+com.galois.fiveui.BatchRunner  - root path for webdriver is /Users/galois/FiveUI/
 com.galois.fiveui.BatchRunner  - loading http://www.whitehouse.gov for ruleset run ...
 com.galois.fiveui.BatchRunner  - running ruleset "Color Guidelines"
 com.galois.fiveui.BatchRunner  - runRule: url=http://www.whitehouse.gov/, ruleSet="Color Guidelines"
 com.galois.fiveui.BatchRunner  - being polite for 1000 millis...
 ```
 
-After the run completes you should see a text log of the run in `reports/basic.out` and an HTML summary report
-in `reports/basic/summary.html`. Note that there are many errors reported on this particular run because the
-rule sets used (particularly the color guidelines) were not designed for whitehouse.gov in particular.
+After the run is complete you should see a text log of the run in
+`reports/basic.out` and an HTML summary report in
+`reports/basic/summary.html`. Note that there are many errors
+reported on this particular run because the rule sets used (particularly
+the color guidelines) were not designed with `whitehouse.gov` in
+mind.
 
 ### Write your own run configuration.
 
-The run configuration is a text file in JSON format that determines the behavior
-of a headless run:
+A run configuration is a text file in JSON format that determines the behavior
+of a Headless run, in particular:
 
- - Location of ruleset files
- - Web crawl parameters
+ - the location of rule set files
+ - web crawl parameters
  - URLs to test (seeds for the crawl)
 
 The format of a run configuration is as follows:
@@ -107,14 +126,14 @@ The format of a run configuration is as follows:
  * Comments
  */
 {
-  'rulePath'  : '<path>',                         // path where rule set files referenced below live
-  'crawlType' : '<d> <n> <p> <pat>',              // d = crawl depth, n = max number of pages to retrieve
+  'rulePath'  : '<path>',                         // path = the path where rule set files referenced below live.
+  'crawlType' : '<d> <n> <p> <pat>',              // d = crawl depth, n = max number of pages to retrieve.
                                                   // p = politeness delay (ms), pat = URL glob pattern
-                                                  // crawlType can also be 'none'
+                                                  // (crawlType can also be 'none').
   'runs': [
-  { 'url': '<url>', 'ruleSet': '<rule_file>' },   // each line here corresponds to a separate webcrawl
-  { 'url': '<url>', 'ruleSet': '<rule_file>' },   // and rule execution pass
-  ...
+  { 'url': '<url>', 'ruleSet': '<rule_file>' },   // Each line here corresponds to a separate webcrawl
+  { 'url': '<url>', 'ruleSet': '<rule_file>' },   // and rule execution pass.
+  ...                                             // Many URL lines may follow.
   ]
 }
 ```
@@ -145,7 +164,7 @@ $ mvn compile
 
 ### Get Firefox E.S.R.
 
-In order to use headless you also need a copy of Firefox 17 (the current
+In order to use Headless you also need a copy of Firefox 17 (the current
 extended support release or E.S.R.). More recent versions of Firefox may also work, but
 they are not supported for use with FiveUI. Download and install Firefox 17
 [here](http://www.mozilla.org/en-US/firefox/organizations/all.html). Note that
@@ -153,7 +172,7 @@ Firefox 17 can be installed along side existing alternate versions of firefox on
 your system or isolated to your user directory by simply moving it's
 installation directory.
 
-Now that you've installed Firefox 17, it's time to tell headless where the
+Now that you've installed Firefox 17, it's time to tell Headless where the
 binary lives. For example, when I install Firefox 17 to `~/myapps/Firefox17` on a
 Mac OS X system, the firefox binary lives at
 
@@ -175,7 +194,7 @@ $ cp programs.properties.example programs.properties
 Now, modify the first entry in `programs.properties`
 to point to the location of your Firefox binary from step 3.
 
-At this point, `headless` is ready to run, see the Quickstart section above for
+At this point, Headless is ready to run, see the Quickstart section above for
 usage examples. The "batteries-included" JAR file has been built and lives at
 `<FiveUI>/headless/target/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar`. Use `java`
 to execute the JAR file manually: