Add tweaks to README.yarn

1 files changed, 23 insertions, 29 deletions

diff --git a/README.yarn b/README.yarn
index 465711d..a117866 100644
--- a/README.yarn
+++ b/README.yarn
@@ -1,19 +1,13 @@
 README for story testing
 ========================
 
-Document History
-----------------
-**TODO: Remove this when finalised**
-v1. liw wrote it
-v2. kinnison updated based on conversation with liw
-
 Introduction
 ------------
 
-`story-test` is a story testing tool: you write a story describing
-how a user uses your software and what should happen, and express,
-using very lightweight syntax, the story in such a way that it can
-be tested automatically. The story has a simple, but strict structure:
+`yarn` is a story testing tool: you write a story describing how a
+user uses your software and what should happen, and express, using
+very lightweight syntax, the story in such a way that it can be tested
+automatically. The story has a simple, but strict structure:
 
     GIVEN some setup for the test
     WHEN thing that is to be tested happens
@@ -28,7 +22,7 @@ a backup program works, at least for one simple case.
     THEN the data case be restored
 
 (Note the addition of AND: you can have multiple GIVEN, WHEN, and
-THEN statements.)
+THEN statements. The AND keyword makes the text be more readable.)
 
 Stories are meant to be written in somewhat human readable language.
 However, they are not free form text. In addition to the GIVEN/WHEN/THEN
@@ -54,10 +48,10 @@ from above might be implemented as follows:
     diff -rq "$TESTDIR/data" "$TESTDIR/restored"
 
 Each "IMPLEMENT GIVEN" (or WHEN, THEN) is followed by a regular
-expression on the same line, and then a shell script that gets
-executed to implement any step that matches the regular expression.
-The implementation can extract data from the match as well: for
-example, the regular expression might allow an amount to be specified.
+expression on the same line, and then a shell script that gets executed
+to implement any step that matches the regular expression.  The
+implementation can extract data from the match as well: for example,
+the regular expression might allow a file size to be specified.
 
 The above example is a bit silly, of course: why go to the effort
 to obfuscate the various steps? The answer is that the various
@@ -90,15 +84,15 @@ The following keywords are defined.
 * **STORY** starts a new story. The rest of the line is the name of
   the story. The name is used for documentation and reporting
   purposes only and has no semantic meaning. STORY MUST be the
-  first keyword in a story, with the exception of IMPLEMENTING.
+  first keyword in a story, with the exception of IMPLEMENTS.
   The set of documents passed in a test run may define any number of
   stories between them, but there must be at least one or it is a
-  test failure. The IMPLEMENTING sections are shared between the
+  test failure. The IMPLEMENTS sections are shared between the
   documents and stories.
 
 * **ASSUMING** defines a condition for the story. The rest of the
   line is "matched text", which gets implemented by an
-  IMPLEMENTING section. If the code executed by the implementation
+  IMPLEMENTS section. If the code executed by the implementation
   fails, the story is skipped.
 
 * **GIVEN** prepares the world for the test to run. If
@@ -111,7 +105,7 @@ The following keywords are defined.
   did the right thing. If the code fails, the story fails.
 
 * **FINALLY** specifies how to clean up after a story. If the
-  code fails, the story fails. All finally blocks get run either when
+  code fails, the story fails. All FINALLY blocks get run either when
   encountered in the story flow, or at the end of the story, regardless
   of whether the story is failing or not.
 
@@ -119,7 +113,7 @@ The following keywords are defined.
   was used last. It must not be used unless the previous step was
   one of those, or another AND.
 
-* **IMPLEMENTING** is followed by one of ASSUMING, GIVEN, WHEN, or
+* **IMPLEMENTS** is followed by one of ASSUMING, GIVEN, WHEN, or
   THEN, and a PCRE regular expression, and then shell commands until
   the end of the block quoted code block. Markdown is unclear whether
   an empty line (no characters, not even whitespace) between two
@@ -129,9 +123,9 @@ The following keywords are defined.
   testing keywords.
 
   The shell commands get parenthesised parts of the match of the
-  regular expression as positional arguments (`$1` etc). For
-  example, if the regexp is "a (\d+) byte file", then `$1` gets
-  set to the number matchec by `\d+`.
+  regular expression as environment variables (`$MATCH_1` etc). For
+  example, if the regexp is "a (\d+) byte file", then `$MATCH_1` gets
+  set to the number matched by `\d+`.
 
   The test runner creates a temporary directory, whose name is
   given to the shell code in the `TESTDIR` environment variable.
@@ -143,7 +137,7 @@ The following keywords are defined.
   cleanly. In addition functions for handling stdout and stderr will
   be provided.
 
-  The code block of an IMPLEMENTING block fails if the shell
+  The code block of an IMPLEMENTS block fails if the shell
   invocation exits with a non-zero exit code. Output to stderr is
   not an indication of failure. Any output to stdout or stderr may
   or may not be shown to the user.
@@ -154,10 +148,10 @@ Semantics:
 * All names will be normalised before use (whitespace collapse, leading
   and trailing whitespace
 * Every ASSUMING, GIVEN, WHEN, THEN, FINALLY must be matched by
-  exactly one IMPLEMENTING. The test runner checks this before running
+  exactly one IMPLEMENTS. The test runner checks this before running
   any code.
-* Every IMPLEMENTING may match any number of ASSUMING, GIVEN, WHEN,
-  THEN, or FINALLY. The test runner can warn if an IMPLEMENTING is unused.
+* Every IMPLEMENTS may match any number of ASSUMING, GIVEN, WHEN,
+  THEN, or FINALLY. The test runner can warn if an IMPLEMENTS is unused.
 * If ASSUMING fails, that story is skipped, and any FINALLY steps
   are not run.
 
@@ -169,7 +163,7 @@ which can provide background and further explanation to what this
 tools tries to do.
 
 [BDD]: https://en.wikipedia.org/wiki/Behavior-driven_development
-[Markdown]: ...
+[Markdown]: http://daringfireball.net/projects/markdown/
 
 TODO
 ----
@@ -180,7 +174,7 @@ TODO
   to localhost when flinging, for example.
   **DJAS**: We think this might be 'REQUIRING' and it still does
   not run the FINALLY group.
-* Consider the ordering some more.  IMPLEMENTING can come anywhere
+* Consider the ordering some more.  IMPLEMENTS can come anywhere
   but otherwise stories are defined as:
     * STORY
     * 0+: ASSUMING