From c05f2346171e4287f3781d28dc29c38da9d0bc5f Mon Sep 17 00:00:00 2001
From: Pete Fotheringham <pete.fotheringham@codethink.co.uk>
Date: Sun, 17 Nov 2013 20:57:11 +0000
Subject: Added the folowing sections

    Running yarn
    Command line syntax and examples
    Using pandoc to format a test suite
---
 yarn-doc/index.mdwn | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 109 insertions(+), 3 deletions(-)

diff --git a/yarn-doc/index.mdwn b/yarn-doc/index.mdwn
index df2fa63..e535633 100644
--- a/yarn-doc/index.mdwn
+++ b/yarn-doc/index.mdwn
@@ -42,11 +42,12 @@ Document Status
     * What kinds of testing is `yarn` for?
     * Why `yarn` instead of other tools?
     * Why not cmdtest?
-
+* Running yarn
+    * Command line syntax and examples
+    * Using `pandoc` to format a test suite
 
 ### What's Next
 
-* `yarn`'s command line
 *  How to embed `yarn` in Markdown
 
 Introduction
@@ -284,7 +285,7 @@ Semantics:
 
 * The name of each scenario (given with SCENARIO) must be unique.
 * All names of scenarios and steps will be normalised before use
-  (whitespace collapse, leading and trailing whitespace
+  (whitespace collapse, leading and trailing whitespace)
 * Every ASSUMING, GIVEN, WHEN, THEN, FINALLY must be matched by
   exactly one IMPLEMENTS. The test runner checks this before running
   any code.
@@ -293,6 +294,111 @@ Semantics:
 * If ASSUMING fails, that scenario is skipped, and any FINALLY steps
   are not run.
 
+Running yarn
+------------
+### Command line syntax
+
+<pre>
+Usage: yarn [options]
+
+Options:
+  --version             show program's version number and exit
+  -h, --help            show this help message and exit
+  --output=FILE         write output to FILE, instead of standard output
+  -n, --no-act, --dry-run, --pretend
+                        do not actually run any tests, merely print what would
+                        be run
+  --no-no-act, --no-dry-run, --no-pretend
+  -q, --quiet           be quiet, avoid progress reporting, only show errors
+  --no-quiet            
+  -v, --verbose         make progress reporting be more verbose ("wall of
+                        text"), instead of a one-line status info; this is
+                        turned automatically if there is not terminal
+  --no-verbose          
+  -s SHELL-LIBRARY, --shell-library=SHELL-LIBRARY
+                        include a shell library for the IMPLEMENTS sections to
+                        use
+  -r TEST, --run=TEST   run only TEST (this option can be repeated)
+  --tempdir=DIR         use DIR as the temporary directory for tests; it
+                        should be empty or not exist
+  --env=NAME=VALUE      add NAME=VALUE to the environment when tests are run
+  --snapshot            make snapshots of test working directory after each
+                        scenario step; you probably want to use this with
+                        --tempdir
+  --no-snapshot         
+  --timings             report wall clock time for each scenario and step
+  --no-timings          
+
+  Configuration files and settings:
+    --dump-config       write out the entire current configuration
+    --no-default-configs
+                        clear list of configuration files to read
+    --config=FILE       add FILE to config files
+    --help-all          show all options
+
+  Logging:
+    --log=FILE          write log entries to FILE (default is to not write log
+                        files at all); use "syslog" to log to system log, or
+                        "none" to disable logging
+    --log-level=LEVEL   log at LEVEL, one of debug, info, warning, error,
+                        critical, fatal (default: debug)
+    --log-max=SIZE      rotate logs larger than SIZE, zero for never (default:
+                        0)
+    --log-keep=N        keep last N logs (10)
+    --log-mode=MODE     set permissions of new log files to MODE (octal;
+                        default 0600)
+
+  Peformance:
+    --dump-memory-profile=METHOD
+                        make memory profiling dumps using METHOD, which is one
+                        of: none, simple, meliae, or heapy (default: simple)
+    --memory-dump-interval=SECONDS
+                        make memory profiling dumps at least SECONDS apart
+</pre>
+
+### Examples
+
+This command will run all the tests in the file `tests.yarn`:
+  
+     $ yarn test.yarn
+     
+This command will run only the test named "Simple test" in the file
+`tests.yarn`:
+  
+     $ yarn test.yarn -r "Simple test"
+     
+This command will run all the tests in all the `.yarn` files in the `tests`
+sub-directory, using the `IMPLEMENTS` in the `shell-lib.sh` shell library:
+  
+     $ yarn --shell-library shell-lib.sh tests/*.yarn
+     
+To Do: how to run yarn under cron or jenkins
+
+### Using `pandoc`
+
+Because `yarn` test suites are written in Markdown, you can use the
+[`pandoc`][pandoc] document converter to format them for printing or
+reading.
+
+These commands will create html and pdf documents containing the test
+scenarios and narrative text from the all the .yarn files in the `tests`
+sub-directory:
+ 
+     $ pandoc -o test-suite.html tests/*.yarn
+     $ pandoc -o test-suite.pdf tests/*.yarn
+
+See also
+--------
+
+Wikipedia has an article on [Behaviour Driven Development][BDD],
+which can provide background and further explanation to what this
+tools tries to do.
+
+[BDD]: https://en.wikipedia.org/wiki/Behavior-driven_development
+[Markdown]: http://daringfireball.net/projects/markdown/
+[Pandoc]: http://johnmacfarlane.net/pandoc/
+
+
 
 Outline
 -------
-- 
cgit v1.2.1