update tutorial to current Subplot

2 files changed, 66 insertions, 77 deletions

diff --git a/docs.mdwn b/docs.mdwn
index 31b49fd..893028a 100644
--- a/docs.mdwn
+++ b/docs.mdwn
@@ -2,3 +2,7 @@
 
 There is a [[tutorial]], which is currently not working, until the
 software has been written.
+
+See also Subplot's own [subplot][].
+
+[subplot]: https://examples.subplot.liw.fi/subplot.html
diff --git a/tutorial.mdwn b/tutorial.mdwn
index c3c1f97..0e4f293 100644
--- a/tutorial.mdwn
+++ b/tutorial.mdwn
@@ -1,33 +1,35 @@
-[[!meta title="Subplot tutorial"]]
-
-NOTE: This tutorial is a little premature, as the software hasn't been
-written yet. The tutorial is based on an earlier prototype.
-
 Introduction
 =============================================================================
 
-Subplot is a tool for **automated testing of acceptance criteria**.
-Acceptance tests define if a program (or other system) is accepable,
-from a user's or 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.
+Subplot is software to help **capture and communicate acceptance
+criteria** for software and systems, and **how they are verified**, in
+a way that's understood by **all project stakeholders**.
+
+Another way to express that is that Subplot is for **automated testing
+of acceptance criteria**. 
 
-Acceptance tests differ from other integration tests by looking at the
-software only from the user's point of view, not the developers'.
+A simplified explanation is that Subplot provides a way to codify
+an agreement of when a customer is required to pay for a project.
+
+Acceptance testing differ from other integration testing by looking at
+the software only from the user's point of view, not the developers'.
 Because of this, Subplot produces two things: a standalone document
 aimed at the user to describe the accepance tests, and a report from
 executing the automated tests.
 
 The document is meant to be a vehicle of communication between the
 various stakeholders in a project, for specifying in detail what the
-acceptance criteria are. The document both explains the criteria, and how
-they're verified, and lets the verification to be done automatically.
+acceptance criteria are. The document both explains the criteria, and
+how they're verified, and makes it possible to do the verification
+automatically.
+
+Subplot generates the document, and a test program to execute the
+tests. Running the generated test program produces the test report.
 
-Subplot generates the document, and a test program to execute the tests.
-The generated test program produces the test report.
+# Architecture
 
 ```dot
+digraph "archiecture" {
 md [label="document source\n(Markdown)"];
 md [shape=box];
 
@@ -55,6 +57,7 @@ impl -> subplot;
 subplot -> pdf;
 subplot -> testprog;
 testprog -> report;
+}
 ```
 
 Example
@@ -79,12 +82,16 @@ These are specified for Subplot in a [Markdown][] document. A minimal
 one for echo might look like this:
 
 ~~~~markdown
+---
+title: echo acceptance criteria
+...
+
 No arguments
 =============================================================================
 
-Run `/bin/echo` without arguments.
+Run `echo` without arguments.
 
-```subplot
+```scenario
 when user runs echo without arguments
 then exit code is 0
 and standard output contains a newline
@@ -94,18 +101,18 @@ and standard error is empty
 Hello, world
 =============================================================================
 
-Run `/bin/echo` to produce the output "hello, world".
+Run `echo` to produce the output "hello, world".
 
-```subplot-scenario
+```scenario
 when user runs echo with arguments hello, world
 then exit code is 0
-and standard output contains "hello, world"
+and standard output contains "hello, world\n"
 and standard error is empty
 ```
 ~~~~
 
 
-Acceptance tests in Subplot are expresses as **scenarios**, which
+Acceptance tests in Subplot are expressed as **scenarios**, which
 roughly correspond to use cases and acceptance
 requirements. A scenario has an overall structure of given/when/then:
 
@@ -114,7 +121,7 @@ requirements. A scenario has an overall structure of given/when/then:
 * **then** the end result looks in a specific way (verify what happened)
 
 These are embedded in markdown using **fenced code blocks** marked as
-containing `subplot-scenario` text. Subplot extracts these and
+containing `scenario` text. Subplot extracts these and
 generates a test program to execute them. 
 
 The scenario steps need to be formulated in a way that all
@@ -126,9 +133,9 @@ collaboration with the client, and approved by the client.
 Subplot is not magic artificial intelligence. Each scenario step needs
 to be implemented by programmers so that computers also understand
 them. Each step corresponds to a function, written in a programming
-language such as Python or Rust, and a YAML file **binds** the step to
-the function, using a pattern to capture relevant parts of the step.
-The pattern can be simple or a full PCRE regular expression. A binding
+language such as Python, and a YAML file **binds** the step to the
+function, using a pattern to capture relevant parts of the step. The
+pattern can be simple or a full PCRE regular expression. A binding
 file might look like this:
 
 ```yaml
@@ -179,25 +186,6 @@ apt update
 apt install subplot
 ```
 
-To run Subplot from git, you need to clone the git repository and need
-Python 3, and the Markdown parser installed, as well as document
-typesetting tools, from Debian 10 (buster) or later:
-
-```sh
-sudo apt update
-sudo apt install make git locales-all pandoc python3 \
-  python3-pandocfilters python3-commonmark-bkrs python3-yaml \
-  texlive-latex-base texlive-fonts-recommended \
-  graphviz librsvg2-bin
-git clone git://git.liw.fi/subplot
-cd subplot
-```
-
-Note that `subplot` contains sample versions of the files for the
-echo acceptance tests (`echo.md`, `echo.yaml`, `echo.py`, and
-`echo-prelude.py`) so that you don't need to type them in yourself.
-
-
 Producing a document
 =============================================================================
 
@@ -206,14 +194,14 @@ the following commands are needed (prefix the commands with "./" if
 running from a git checkout):
 
 ```sh
-docgen --html echo.md
-docgen --pdf echo.md
+sp-docgen echo.md -o echo.html
+dp-docgen echo.md -o echo.pdf
 ```
 
-`echo.md` is the markdown input file. `echo.yaml` is the bindings, and
-its name is inferred by `docgen`. `echo.pdf` and `echo.html` are the
-formatted documents. The input files are included in the `subplot` git
-repository.
+`echo.md` is the markdown input file. Subplot will find `echo.yaml`
+(the bindings) and `echo.py` or `echo.sh` (step implementations in
+Python or Bash) from files mentioned in the markdown file's metadata
+section.
 
 
 
@@ -224,36 +212,28 @@ To generate the test program, and running it to produce the test
 report, the following commands are needed:
 
 ```sh
-codegen --run echo.md
+sp-codegen echo.md -o test.py --run
 ```
 
 The output of the last command is the test report:
 
+```{.numberLines}
+srcdir /home/liw/pers/subplot/subplot
+datadir /tmp/tmp.MeW2f5NS7n
+scenario: No arguments
+  step: when user runs echo without arguments
+  step: then exit code is 0
+  step: then standard output contains a newline
+  step: then standard error is empty
+  cleanup: 
+scenario: Hello, world
+  step: when user runs echo with arguments hello, world
+  step: then exit code is 0
+  step: then standard output contains "hello, world"
+  step: then standard error is empty
+  cleanup: 
+OK, all scenarios finished successfully
 ```
-OK: No arguments
-OK: Hello, world
-```
-
-`echo.yaml` and `echo.md` are again the bindings and markdown files.
-Also, `echo.py` has the Python functions, needed at runtime, though
-not referenced above. The names of `echo.py` and `echo.yaml` are
-inferred by `ftt-codegen`.
-
-
-
-Exercise
-=============================================================================
-
-Your mission, should you choose to accept it, is to write a Subplot to
-write an acceptance test suite for simple uses of the **cp**(1)
-command. You can model it after the **echo**(1) one, and you get to
-specify the actual acceptance criteria yourself. For the exercise,
-it's enough for you to check that a regular file can be copied to
-another name in the same directory and that the end result is the
-same. You should try to get `docgen` produce a PDF of your subplot.
-You don't need to run the tests.
-
-
 
 Finally
 =============================================================================
@@ -276,3 +256,8 @@ Questions for after you go through the tutorial:
 * Did you have any problems following the tutorial?
 * Do you see yourself using Subplot in the future?
 * Do you see Subplot as filling a gap?
+
+
+---
+title: Subplot tutorial
+...