From 1e6779632640d6c47ea3657ba00df9c306ca4f18 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Sun, 9 Jun 2019 09:18:48 +0300
Subject: Change: linguistic improvements to tutorial.md

---
 tutorial.md | 57 +++++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 45 insertions(+), 12 deletions(-)

(limited to 'tutorial.md')

diff --git a/tutorial.md b/tutorial.md
index 9c0daa4..8be560f 100644
--- a/tutorial.md
+++ b/tutorial.md
@@ -16,7 +16,7 @@ client's or employer's point of view. Basically, in a commercial
 consulting setting, acceptance tests determine if the client is
 willing to pay the bill for the software having been developed.
 
-Acceptance tests differ from integration tests by looking at the
+Acceptance tests differ from other integration tests by looking at the
 software _only_ from the user's point of view, not the developer's.
 Because of this, Fable produces two things: a standalone document
 aimed at the user to describe the accepance tests, and a report from
@@ -30,6 +30,35 @@ they're verified, and lets the verification to be done automatically.
 Fable generates the document, and a test program to execute the tests.
 The generated test program produces the test report.
 
+```dot
+md [label="document source\n(Markdown)"];
+md [shape=box];
+
+bindings [label="bindings file\n(YAML)"];
+bindings [shape=box];
+
+impl [label="step implementations\n(Python, Rust, ...)"]
+impl [shape=box];
+
+fable [label="Fable"];
+fable [shape=ellipse];
+
+pdf [label="PDF document"]
+pdf [shape=box];
+
+testprog [label="Test program\n(generated)"]
+testprog [shape=box];
+
+report [label="Test report"]
+report [shape=box];
+
+md -> fable;
+bindings -> fable;
+impl -> fable;
+fable -> pdf;
+fable -> testprog;
+testprog -> report;
+```
 
 Example
 =============================================================================
@@ -77,7 +106,7 @@ one for echo might look like this:
     ```
 
 Acceptance tests in Fable are expresses as **scenarios**, which
-roughly correspond to use cases and one or more acceptance
+roughly correspond to use cases and acceptance
 requirements. A scenario has an overall structure of given/when/then:
 
 * **given** some initial context (setup)
@@ -119,14 +148,17 @@ This means that for a step saying 'then standard output contains
 string `foo` as an argument.
 
 You, or your test team, in collaboration with the development team,
-need to supply the bindings and the Python functions.
+need to supply the bindings and the Python functions. Fable produces
+the code that extracts the interesting parts of scenario steps, and
+calls your functions in the right order, plus any other scaffolding
+needed.
 
-Installing fable
+Installing Fable
 =============================================================================
 
 Fable is not currently packaged for Debian. You need to clone the git
 repository and need Python 3, and the Markdown parser installed, as
-well as document typesetting tools:
+well as document typesetting tools, from Debian 10 (buster) or later:
 
 ```sh
 sudo apt install python3 python3-commonmark-bkrs pandoc texlive-full
@@ -148,11 +180,12 @@ the following commands are needed:
 ```sh
 ./ftt-docgen echo.yaml echo.md > tmp.md
 ./pandoc.sh tmp.md -o tmp.pdf
+./pandoc.sh tmp.md -o tmp.html
 ```
 
-`echo.yaml` is the bindings. `echo.md` is the markdown. `tmp.pdf` is
-the formatted document. The files are included in the `fable-poc` git
-repository.
+`echo.yaml` is the bindings. `echo.md` is the markdown. `tmp.pdf` and
+`tmp.html` are the formatted documents. The source files are included
+in the `fable-poc` git repository.
 
 Running the tests
 =============================================================================
@@ -181,7 +214,7 @@ Exercise
 
 Your missiong, should you choose to accept it, is to write use Fable
 to write an acceptance test suite for simple uses of the **cp**(1)
-command. You can model it after the echo one, and you get to specify
-the actual acceptance criteria yourself, but at minimum you need to
-check that a regular file can be copied to another name and that the
-end result is the same.
+command. You can model it after the **echo**(1) one, and you get to
+specify the actual acceptance criteria yourself, but at minimum you
+need to check that a regular file can be copied to another name and
+that the end result is the same.
-- 
cgit v1.2.1