doc: refactor subplot.md document structure for clarity

Drop unnecessary sections, combine sections to belong together under
a common parent, move things that don't belong under a parent to be on
their own. All in the name of a clearer document and arguable correctness.

1 files changed, 45 insertions, 51 deletions

diff --git a/subplot.md b/subplot.md
index ccfc7b4..bcd4eb9 100644
--- a/subplot.md
+++ b/subplot.md
@@ -455,10 +455,6 @@ They're separate from the scenarios so that the scenarios are shorter
 and clearer, but also so that the input files do no need to be
 duplicated for each scenario.
 
-
-
-### A simple scenario (simple.md)
-
 ~~~~{#simple.md .file .markdown .numberLines}
 ---
 title: Test scenario
@@ -476,9 +472,6 @@ then bar was done
 ```
 ~~~~
 
-
-### Bindings file (b.yaml)
-
 ~~~{#b.yaml .file .yaml .numberLines}
 - given: precondition foo
   function: precond_foo
@@ -492,7 +485,6 @@ then bar was done
   function: foobar_was_done
 ~~~
 
-### Python functions (f.py)
 
 ~~~{#f.py .file .python .numberLines}
 def precond_foo(ctx):
@@ -667,9 +659,6 @@ and step "then bar was done" was run
 and program finished successfully
 ~~~
 
-
-### A document with a scenario with empty lines (emptylines.md)
-
 ~~~~{#emptylines.md .file .markdown .numberLines}
 ---
 title: Test scenario
@@ -1262,7 +1251,13 @@ then exit code is non-zero
 ~~~
 
 
-## Running only chosen scenarios with Python
+## Running only chosen scenarios
+
+To make the edit-test loop more convenient for the test programs
+generated by Subplot, we allow the user to specify patterns for
+scenarios to run. Default is to run all scenarios.
+
+### Running only chosen scenarios with Python
 
 This verifies that the generated Python test program can run only
 chosen scenarios.
@@ -1302,7 +1297,7 @@ then bar was done
 ```
 ~~~
 
-## Running only chosen scenarios with Bash
+### Running only chosen scenarios with Bash
 
 This verifies that the generated Bash test program can run only
 chosen scenarios.
@@ -1463,43 +1458,6 @@ and file mtime.html contains "Geoffrey Butler"
 and file mtime.html contains "2020-02-26 07:53"
 ~~~
 
-### Using as a Pandoc filter
-
-Subplot can be used as a Pandoc _filter_, which means Pandoc can allow
-Subplot to modify the document while it is being converted or typeset.
-This can useful in a variety of ways, such as when using Pandoc to
-improve Markdown processing in the [ikiwiki][] blog engine.
-
-[ikiwiki]: http://ikiwiki.info/
-
-The way filters work is that Pandoc parses the input document into an
-abstract syntax tree, serializes that into JSON, gives that to the
-filter (via the standard input), gets a modified abstract syntax tree
-(again as JSON, via the filter's standard output).
-
-Subplot supports this via the **sp-filter** executable. It is built
-using the same internal logic as Subplot's docgen. The interface is
-merely different to be usable as a Pandoc filter.
-
-This scenarios verifies that the filter works at all. More
-importantly, it does that by feeding the filter a Markdown file that
-does not have a YAML metadata block. For the ikiwiki use case, that's
-what the input files are like.
-
-~~~scenario
-given file justdata.md
-when I run pandoc --filter sp-filter justdata.md -o justdata.html
-then file justdata.html matches /does not have a YAML metadata/
-~~~
-
-The input file **justdata.md**:
-
-~~~~~~~~{#justdata.md .file .markdown .numberLines}
-This is an example Markdown file.
-It does not have a YAML metadata block.
-~~~~~~~~
-
-
 ### Extracting metadata from a document
 
 The **sp-meta** program extracts metadata from a document. It is
@@ -2058,12 +2016,48 @@ This content is foobarish
 
 ~~~~~~~~
 
+## Using as a Pandoc filter
+
+Subplot can be used as a Pandoc _filter_, which means Pandoc can allow
+Subplot to modify the document while it is being converted or typeset.
+This can useful in a variety of ways, such as when using Pandoc to
+improve Markdown processing in the [ikiwiki][] blog engine.
+
+[ikiwiki]: http://ikiwiki.info/
+
+The way filters work is that Pandoc parses the input document into an
+abstract syntax tree, serializes that into JSON, gives that to the
+filter (via the standard input), gets a modified abstract syntax tree
+(again as JSON, via the filter's standard output).
+
+Subplot supports this via the **sp-filter** executable. It is built
+using the same internal logic as Subplot's docgen. The interface is
+merely different to be usable as a Pandoc filter.
+
+This scenarios verifies that the filter works at all. More
+importantly, it does that by feeding the filter a Markdown file that
+does not have a YAML metadata block. For the ikiwiki use case, that's
+what the input files are like.
+
+~~~scenario
+given file justdata.md
+when I run pandoc --filter sp-filter justdata.md -o justdata.html
+then file justdata.html matches /does not have a YAML metadata/
+~~~
+
+The input file **justdata.md**:
+
+~~~~~~~~{#justdata.md .file .markdown .numberLines}
+This is an example Markdown file.
+It does not have a YAML metadata block.
+~~~~~~~~
+
+
 
   
 ---
 title: "Subplot"
 author: The Subplot project
-date: work in progress
 bindings: 
 - subplot.yaml
 - runcmd.yaml