tests(subplot.md): update subplot for Pandoc-less future

Sponsored-by: author

1 files changed, 51 insertions, 104 deletions

diff --git a/subplot.md b/subplot.md
index a294573..934623e 100644
--- a/subplot.md
+++ b/subplot.md
@@ -20,20 +20,20 @@ document.
 
 We define the various concepts relevant to Subplot as follows:
 
-* **Acceptance criteria**: What the stakeholders require of the system
+* **Acceptance criteria:** What the stakeholders require of the system
   for them to be happy with it and use it.
 
-* **Stakeholder**: Someone with a keen interest in the success of a
+* **Stakeholder:** Someone with a keen interest in the success of a
   system. They might be a paying client, someone who uses the system,
   or someone involved in developing the system. Depending on the
   system and project, some stakeholders may have a bigger say than
   others.
 
-* **Acceptance test**: How stakeholders verify that the system
+* **Acceptance test:** How stakeholders verify that the system
   fulfills the acceptance criteria, in an automated way. Some criteria
   may not be possible to verify automatically.
 
-* **Scenario**: In Subplot, the acceptance criteria are written as
+* **Scenario:** In Subplot, the acceptance criteria are written as
   freeform prose, with diagrams, etc. The scenarios, which are
   embedded blocks of Subplot scenario language, capture the mechanisms
   of verifying that criteria are met - the acceptance tests - showing
@@ -103,13 +103,7 @@ testprog -> report;
 }
 ```
 
-[Pandoc]: https://pandoc.org/
-
-Subplot uses the [Pandoc][] software for generating HTML
-output documents. In fact, any output format supported by Pandoc can
-be requested by the user. Depending on the output format, Pandoc may
-use, for example, LaTeX. Subplot interprets parts of the Markdown
-input file itself.
+Subplot generated HTML itself.
 
 Subplot actually consists mainly of two separate programs:
 **subplot docgen** for generating output documents, and **subplot codegen** for
@@ -307,56 +301,56 @@ tests for Subplot](#acceptance).
 Each requirement here is given a unique mnemonic id for easier
 reference in discussions.
 
-**UnderstandableTests**
+*   **UnderstandableTests**
 
-:   Acceptance tests should be possible to express in a way that's
-    easily understood by all stakeholders, including those who are
-    not software developers.
+    Acceptance tests should be possible to express in a way that's
+    easily understood by all stakeholders, including those who are not
+    software developers.
 
     _Done_ but requires the Subplot document to be written with care.
 
-**EasyToWriteDocs**
+*   **EasyToWriteDocs**
 
-:   The markup language for writing documentation should be easy to
+    The markup language for writing documentation should be easy to
     write.
 
     _Done_ by using Markdown.
 
-**AidsComprehension**
+*   **AidsComprehension**
 
-:   The formatted human-readable documentation should use good layout
+    The formatted human-readable documentation should use good layout
     and typography to enhance comprehension.
 
-    _In progress_ — typesetting via Pandoc works, but may need
-    review and improvement.
+    _In progress_ — we currently only output HTML, but may add
+    PDF output back later.
 
-**CodeSeparately**
+*   **CodeSeparately**
 
-:   The code to implement the acceptance criteria should not be
+    The code to implement the acceptance criteria should not be
     embedded in the documentation source, but be in separate files.
     This makes it easier to edit without specialised tooling.
 
     _Done_ by keeping scenario step implementations in a separate
     file.
 
-**AnyProgammingLanguage**
+*   **AnyProgammingLanguage**
 
-:   The developers implementing the acceptance tests should be free to
+    The developers implementing the acceptance tests should be free to
     use a language they're familiar and comfortable with. Subplot
     should not require them to use a specific language.
 
     _Not done_ — only Python supported at the moment.
 
-**FastTestExecution**
+*   **FastTestExecution**
 
-:   Executing the acceptance tests should be fast.
+    Executing the acceptance tests should be fast.
 
     _Not done_ — the generated Python test program is simplistic
     and linear.
 
-**NoDeployment**
+*   **NoDeployment**
 
-:   The acceptance test tooling should assume the system under test is
+    The acceptance test tooling should assume the system under test is
     already deployed and available. Deploying is too big of a problem
     space to bring into the scope of acceptance testing, and there are
     already good tools for deployment.
@@ -364,9 +358,9 @@ reference in discussions.
     _Done_ by virtue of letting those who implement the scenario steps
     worry about it.
 
-**MachineParseableResults**
+*   **MachineParseableResults**
 
-:   The tests should produce a machine parseable result that can be
+    The tests should produce a machine parseable result that can be
     archived, post-processed, and analyzed in ways that are of
     interest to the project using Subplot. For example, to see trends
     in how long tests take, how often tests fail, to find regressions,
@@ -379,16 +373,13 @@ reference in discussions.
 
 Subplot reads three input files, each in a different format:
 
-* The document file, which uses the Markdown dialects understood by
-  Pandoc.
+* The document file in [GitHub Flavored Markdown](https://github.github.com/gfm/).
 * The bindings file, in YAML.
 * The functions file, in Bash or Python.
 
 Subplot interprets marked parts of the input document
-specially. It does this via the Pandoc abstract syntax tree, rather
-than text manipulation, and thus anything that Pandoc understands is
-understood by Subplot. We will not specify Pandoc's dialect of
-Markdown here, only the parts Subplot pays attention to.
+specially. These are fenced code blocks tagged with the `sceanrio`,
+`file`, or `example` classes.
 
 
 ## Scenario language
@@ -513,14 +504,9 @@ will deal with formatting that nicely for you.
 
 ## Document markup
 
-[Pandoc]: https://pandoc.org/
-
-Subplot uses [Pandoc][], the universal document converter, to parse
-the Markdown file, and thus understands the variants of Markdown that
-Pandoc supports. This includes traditional Markdown, CommonMark, and
-GitHub-flavored Markdown.
+Subplot parses Markdown input files using GitHub-flavored Markdown.
 
-[fenced code blocks]: https://pandoc.org/MANUAL.html#fenced-code-blocks
+[fenced code blocks]: https://github.github.com/gfm/#fenced-code-blocks
 
 Subplot extends Markdown by treating certain certain tags for [fenced
 code blocks][] specially. A scenario, for example, would look like
@@ -553,11 +539,7 @@ This data is accessible to the test program as 'filename'.
 
 The `.file` attribute is necessary, as is the identifier, here
 `#filename`. The generated test program can access the data using the
-identifier (without the #). The mechanism used is generic to Pandoc,
-and can be used to affect the typesetting by adding more attributes.
-For example, Pandoc can typeset the data in the code block using
-syntax highlighting, if the language is specified: `.markdown`,
-`.yaml`, or `.python`, for example.
+identifier (without the #).
 
 Subplot also understands the `dot` and `roadmap` tags, and can use the
 Graphviz dot program, or the [roadmap][] Rust crate, to produce
@@ -613,31 +595,23 @@ given file not-numbered-lines.txt
 
 ## 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
+Document metadata is read from a YAML file. This can used to set the
+document title, authors, date (version), and more. Crucially for
+Subplot, the bindings and functions files are named in the metadata
+block, rather than Subplot deriving them from the input file name.
 
-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}
----
+~~~{.file .yaml .numberLines}
 title: "Subplot"
 authors:
 - The Subplot project
 date: work in progress
+markdowns:
+- subplot.md
 bindings:
 - subplot.yaml
 impls:
   python:
     - subplot.py
-...
 ~~~
 
 There can be more than one bindings or functions file: use a YAML
@@ -1193,6 +1167,7 @@ but foobar was done
 ```
 ~~~
 
+<!-- disabled until Lars fixes typesetting of scenarios
 ### Keyword aliases in output
 
 We support **and** and **but** in input lines, and we always render
@@ -1234,6 +1209,7 @@ then bar was done
 then foobar was done
 ```
 ~~~
+-->
 
 ### Misuse of continuation keywords
 
@@ -2174,9 +2150,7 @@ given precondition foo
 
 The document and code generators require a document title, because
 it's a common user error to not have one, and Subplot should help make
-good documents. The Pandoc filter, however, mustn't require a document
-title, because it's used for things like formatting websites using
-ikiwiki, and ikiwiki has a different way of specifying page titles.
+good documents.
 
 #### Document generator gives an error if input document lacks title
 
@@ -2496,32 +2470,6 @@ and file mtime.html contains "Geoffrey Butler"
 and file mtime.html contains "2020-02-26 07:53"
 ~~~
 
-### Pandoc metadata
-
-~~~scenario
-given file pandoc.subplot
-given file pandoc.md
-and an installed subplot
-when I run subplot docgen pandoc.subplot -o pandoc.html
-when I run cat pandoc.html
-then file pandoc.html exists
-and file pandoc.html contains "<title>The Fabulous Title</title>"
-and file pandoc.html contains "Superlative Subtitle"
-~~~
-
-~~~{#pandoc.subplot .file .yaml .numberLines}
-title: The Fabulous Title
-markdowns:
-- pandoc.md
-pandoc:
-  subtitle: Superlative Subtitle
-~~~
-
-~~~{#pandoc.md .file .markdown .numberLines}
-# Introduction
-This is a test document. That's all.
-~~~
-
 ### Missing bindings file
 
 If a bindings file is missing, the error message should name the
@@ -2708,12 +2656,11 @@ bibliography: [foo.bib, bar.bib]
 Subplot allows data files to be embedded in the input document. This
 is handy for small test files and the like.
 
-Handling of a newline character on the last line is tricky. Pandoc
-doesn't include a newline on the last line. Sometimes one is
-needed&mdash;but sometimes it's not wanted. A newline can be added by
-having an empty line at the end, but that is subtle and easy to miss.
-Subplot helps the situation by allowing a `add-newline=` class to be added
-to the code blocks, with one of three allowed cases:
+Handling of a newline character on the last line is tricky. The block
+ends in a newline on the last line. Sometimes one is needed&mdash;but
+sometimes it's not wanted. Subplot helps the situation by allowing a
+`add-newline=` class to be added to the code blocks, with one of three
+allowed cases:
 
 * no `add-newline` class&mdash;default handling: same as `add-newline=auto`
 * `add-newline=auto`&mdash;add a newline, if one isn't there
@@ -3186,7 +3133,7 @@ when I run subplot docgen pikchr.subplot -o pikchr.html
 then file pikchr.html matches regex /src="data:image/svg\+xml;base64,/
 ~~~
 
-The sample input file **pikchr.md**:
+The sample input file **pikchr.md:**
 
 ~~~~~~~~{#pikchr.md .file .markdown .numberLines}
 ---
@@ -3233,7 +3180,7 @@ when I run subplot docgen dot.subplot -o dot.html
 then file dot.html matches regex /src="data:image/svg\+xml;base64,/
 ~~~
 
-The sample input file **dot.md**:
+The sample input file **dot.md:**
 
 ~~~~~~~~{#dot.md .file .markdown .numberLines}
 This is an example Markdown file, which embeds a diagram using dot markup.
@@ -3282,7 +3229,7 @@ when I run subplot docgen plantuml.subplot -o plantuml.html
 then file plantuml.html matches regex /src="data:image/svg\+xml;base64,/
 ~~~
 
-The sample input file **plantuml.md**:
+The sample input file **plantuml.md:**
 
 ~~~~~~~~{#plantuml.md .file .markdown .numberLines}
 This is an example Markdown file, which embeds a diagram using
@@ -3370,7 +3317,7 @@ when I run subplot docgen roadmap.subplot -o roadmap.html
 then file roadmap.html matches regex /src="data:image/svg\+xml;base64,/
 ~~~
 
-The sample input file **roadmap.md**:
+The sample input file **roadmap.md:**
 
 ~~~~~~~~{#roadmap.md .file .markdown .numberLines}
 This is an example Markdown file, which embeds a roadmap.
@@ -3430,7 +3377,7 @@ markdowns:
 
 When Subplot loads a document it will validate that the block classes
 match a known set.  Subplot has a built-in set which it treats as special,
-and it knows some pandoc-specific classes and a number of file type classes.
+and it knows some custom classes and a number of file type classes.
 
 If the author of a document wishes to use additional class names then they can
 include a `classes` list in the document metadata which subplot will treat