Merge branch 'scenario-language' into 'main'

Scenario language

See merge request larswirzenius/subplot!133

1 files changed, 68 insertions, 22 deletions

diff --git a/subplot.md b/subplot.md
index 65f9830..d701995 100644
--- a/subplot.md
+++ b/subplot.md
@@ -307,34 +307,50 @@ understood by Subplot. We will not specify Pandoc's dialect of
 Markdown here, only the parts Subplot pays attention to.
 
 
-## Document metadata
+## Scenario language
 
-Pandoc supports, and Subplot makes use of, a [YAML metadata block][] in a
-Markdown document. This can and should be used to set the document
-title, authors, date (version), and can be used to control some of the
-typesetting. Crucially for Subplot, the bindings and functions files
-are named in the metadata block, rather than Subplot deriving them
-from the input file name.
+The scenarios are core to Subplot. They express what the detailed
+acceptance criteria are and how they're verified. The scenarios are
+meant to be understood by both all human stakeholders and the Subplot
+software. As such, they are expressed in a somewhat stilted language
+that resembles English, but is just formal enough that it can also be
+understood by a computer.
 
-[YAML metadata block]: https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
+A scenario is a sequence of steps. A step can be setup to prepare for
+an action, an action, or an examination of the effect an action had.
+For example, a scenario to verify that a backup system works might
+look like the following:
 
-As an example, the metadata block for the Subplot document might look
-as follows. The `---` before and `...` after the block are mandatory:
-they are how Pandoc recongizes the block.
-
-~~~{.yaml .numberLines}
----
-title: "Subplot"
-author: The Subplot project
-date: work in progress
-bindings: subplot.yaml
-functions: subplot.py
-...
+~~~~~~{.markdown .numberLines}
+~~~scenario
+given a backup server
+when I make a backup
+and I restore the backup
+then the restored data is identical to the original data
 ~~~
+~~~~~~
 
-There can be more than one bindings or functions file: use a YAML
-list.
+This is not magic. The three kinds of steps are each identified by the
+first word in the step.
+
+* `given` means it's a step to set up the environment for the scenario
+* `when` means it's a step with the action that the scenario verifies
+* `then` means it's a step to examine the results of the action
 
+The `and` keyword is special in that it means the step is the same
+kind as the previous step. In the example, on line 4, it means the
+step is a `when` step.
+
+Each step is implemented by a bit of code, provided by the author of
+the subplot document. The step is _bound_ to the code via a binding
+file, via the text of the step: if the text is like this, then call
+that function. Bindings files are described in detail shortly below.
+
+The three kinds of steps exist to make scenarios easier to understand
+by humans. Subplot itself does not actually care if a step is setup,
+action, or examination, but it's easier for humans reading the
+scenario, or writing the corresponding code, if each step only does
+the kind of work that is implied by the kind of step it's bound to.
 
 ## Document markup
 
@@ -426,6 +442,36 @@ This is still line number three, but would it be obvious?
 [roadmap]: https://crates.io/search?q=roadmap
 
 
+## Document metadata
+
+Pandoc supports, and Subplot makes use of, a [YAML metadata block][] in a
+Markdown document. This can and should be used to set the document
+title, authors, date (version), and can be used to control some of the
+typesetting. Crucially for Subplot, the bindings and functions files
+are named in the metadata block, rather than Subplot deriving them
+from the input file name.
+
+[YAML metadata block]: https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
+
+As an example, the metadata block for the Subplot document might look
+as follows. The `---` before and `...` after the block are mandatory:
+they are how Pandoc recongizes the block.
+
+~~~{.yaml .numberLines}
+---
+title: "Subplot"
+author: The Subplot project
+date: work in progress
+template: python
+bindings: subplot.yaml
+functions: subplot.py
+...
+~~~
+
+There can be more than one bindings or functions file: use a YAML
+list.
+
+
 ## Bindings file
 
 The bindings file binds scenario steps to code functions that