Change: linguistic improvements in the arch doc

1 files changed, 36 insertions, 35 deletions

diff --git a/fable-arch.md b/fable-arch.md
index 5c2d86e..0c5faf7 100644
--- a/fable-arch.md
+++ b/fable-arch.md
@@ -20,17 +20,25 @@ abstract: |
   language.
 ...
 
+# Beware
+
+This document describes a future that will be, not current status quo.
+Fable is its initial, active development period, and we don't want to
+update this document every time we make a change. Thus, be aware that
+parts of this document is speculative and may describe a version of
+Fable that does not yet exist.
+
 # Introduction
 
-Fable is a tool for acceptance testing of software. This means it helps
-software developers to make sure their software fulfils the
-acceptance criteria for the software. Such criteria may come from
-users, the developers, their employers, or elsewhere.
+Fable is a tool for acceptance testing of software. It helps software
+developers make sure their software fulfils the acceptance criteria
+for the software. Such criteria may come from paying clients, users,
+the developers, their employers, or elsewhere.
 
 Fable is specifically meant for automated acceptance testing. It takes a
 two-pronged approach, where it lets developers write automated
 tests for all the acceptance criteria they have, and runs the tests.
-On the other hand, Fable also produces a PDF file, which documents the
+On the other hand, Fable also produces a standalone file, which documents the
 automated tests for non-technical stakeholders, such as project
 managers and clients.
 
@@ -46,7 +54,7 @@ shareholders of the software being developed.
 
 Fable's overall working principle is that the tests are implemented and
 documented in a number of source files, which Fable reads to execute
-tests, and to produce a PDF document for non-developer consumption.
+tests, and to produce a document for non-developer consumption.
 
 # Fable architecture
 
@@ -80,12 +88,12 @@ fable -> testprog;
 testprog -> report;
 ```
 
-Fable's architecture it to read input files, and produce two outputs.
+Fable reads input files, and produces two outputs.
 On the one hand, it outputs a program that executes the tests
 specified in the input files. The person running Fable then runs the
 test program to get a test report, with results of each of the test
 scenarios. On the other hand it outputs a human-readable document (as
-PDF), for communicating what is being tested.
+PDF or HTML), for communicating what is being tested.
 
 Fable is able to produce the test program in various languages, using
 a templating system to make it simple to add support for more
@@ -106,7 +114,7 @@ to detect unintentional dependencies between scenarios.
 
 Fable input consists of three types of files:
 
-* one or more markdown files which document that acceptance tests
+* one or more markdown files which document the acceptance tests
 * a binding file (in YAML) which binds scenario steps to their
   implementations
 * scenario step implementations, which are implemented in some
@@ -124,7 +132,7 @@ step implementation in Python).
 [Cucumber]: https://en.wikipedia.org/wiki/Cucumber_(software)
 
 The Fable input language is markdown files using [fenced code blocks][]
-with backticks. The code blocks MUST indicate that they contain Fable
+with backticks. The code blocks must indicate that they contain Fable
 language:
 
     ```fable
@@ -134,21 +142,17 @@ language:
     then it's OK
     ```
 
-Any other code blocks are ignored by Fable and can be used for, say,
-code examples.
+Code blocks for the PlantUML or GraphViz dot markup languages are
+also supported. These can be used for generating embedded images in
+the documented produced by Fable.
 
-FIXME: Later, we may want to add support for embedding
-PlantUML or Graphviz Dot markup, and generate images from that
-automatically. This would look like the example below, and Fable would
-replace the code block with the generated image in the PDF output.
-
-    ```dot
-    foo -> bar
-    ```
+Any unfenced code blocks (indented code blocks) are ignored by Fable,
+as are fenced code blocks using unknown content types.
 
-Fable understands the full Markdown language, by ignoring everything
-except its own code blocks and headings. It uses [Pandoc][] to produce
-PDF files, and anything that Pandoc supports is OK to use.
+The Fable code generator understands the full Markdown language, by
+ignoring everything except headings and its own code blocks. The Fable
+document generator uses [Pandoc][] to produce standalone files, and
+anything that Pandoc supports is OK to use.
 
 [Pandoc]: https://pandoc.org/
 
@@ -159,7 +163,7 @@ document in any way that aids human understanding of the acceptance
 test suite, which the caveat that chapter or section headings are used
 by Fable to group code blocks into scenarios.
 
-All code blocks for the same scenario MUST be grouped under a single
+All code blocks for the same scenario must be grouped under a single
 heading. Sub-headings are permitted within a scenario, but the next
 heading at the same or a higher level will end the scenario. This
 allows for scenarios to begin at any level, but not to leak into a
@@ -179,23 +183,20 @@ The language understood by Fable has the following general structure:
 * logical lines define steps in a test scenario
 * the meaning and implementation of the steps are defined by other
   Fable input files
-* the keywords are: ASSUMING, USING, GIVEN, WHEN, THEN, AND, with
+* the keywords are: ASSUMING, USING, GIVEN, WHEN, THEN, and AND, with
   meanings defined below; keywords can be written in upper or lower
   case, or mixes, Fable doesn't care
 
 The keywords have the following meanings:
 
-* ASSUMING—a condition for the scenario; all ASSUMING steps MUST
-  be at the beginning of the scenario, and may not be preceded by
-  other steps; if the condition fails, the scenario is skipped.
+* ASSUMING—a condition for the scenario. If an ASSUMING step
+  fails, the scenario is skipped.
 
   This is used for skipping test scenarios that require specific
   software to be installed in the test environment, or access to
   external services, but which can't be required for all runs of the
   acceptance tests.
 
-  All ASSUMING steps MUST come first in the scenario.
-
 * USING—indicate that the scenario uses a resource such as a
   database, that's constrained and can't be used by all scenarios if
   they run concurrently. When scenarios declare the resource, Fable can
@@ -213,20 +214,17 @@ The keywords have the following meanings:
   The actual management of resources belongs to the generated test
   program at runtime, not the Fable compiler.
 
-  All USING steps MUST come at the beginning of the scenario, except
-  the ASSUMING steps may precede them.
-
 * GIVEN—set up the test environment for the action (WHEN). This
   might create files, start a background process, or something like
   that. This also sets up the reversal of the setup, so that any
   background processes are stopped automatically after the scenario
-  has ended. The setup and cleanup MUST succeed, or the scenario will
+  has ended. The setup and cleanup must succeed, or the scenario will
   fail.
 
   The cleanups are executed in the reverse order of the GIVENs, and
   they're done always, whether the scenario succeeds or not.
 
-* WHEN—perform the action that is being tested. This MUST
+* WHEN—perform the action that is being tested. This must
   succeed. This might, for example, execute a command line program,
   and capture its output and exit code.
 
@@ -240,6 +238,9 @@ The keywords have the following meanings:
   a step "THEN output is empty" might be followed by "AND the exit
   code is 0" rather than "THEN the exit code is 0".
 
+The order of steps is somewhat constrainted: first any ASSUMING steps,
+then any USING steps, at least one WHEN must come before a THEN.
+
 ## Bindings
 
 FIXME: The binding specification needs thought. This is just a sketch.