subplot.md: Improve bindings documentation

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>

1 files changed, 50 insertions, 10 deletions

diff --git a/subplot.md b/subplot.md
index dee393f..2ccc968 100644
--- a/subplot.md
+++ b/subplot.md
@@ -646,11 +646,24 @@ The bindings file binds scenario steps to code functions that
 implement the steps. The YAML file is a list of objects (also known as
 dicts or hashmaps or key/value pairs), specifying a step kind (given,
 when, then), a pattern matching the text of the step and
-optionally capturing interesting parts of the text, and the name of a
-function that implements the step. 
-
-Patterns can be simple or full-blown Perl-compatible regular
-expresssions ([PCRE][]).
+optionally capturing interesting parts of the text. Each binding may contain
+a type map which tells subplot the types of the captures in the patterns so
+that they can be validated to some extent, and a binding will list some number
+of implementations, each of which is specified by the name of the language
+(template) it is for, and then the name of a function that implements the step,
+optionally with the name of a function to call to clean up a scenario which
+includes that step.
+
+There are some flexibilities in bindings, futher details can be found below:
+
+1. Patterns can be simple or full-blown Perl-compatible regular
+   expresssions ([PCRE][]).
+2. Bindings _may_ have type maps.  Without a type map, all captures are
+   considered to be short strings (words).
+3. Bindings _may_ have as many or as few implementations as needed.  A zero
+   `impl` binding will work for `docgen` but will fail to `codegen`.  This can
+   permit document authors to prepare bindings without knowing how an engineer
+   might implement it.
 
 ~~~{.yaml .numberLines}
 - given: "a standard setup"
@@ -674,7 +687,8 @@ expresssions ([PCRE][]).
       function: check_everything_is_ok
 ~~~
 
-In the example above, there are four bindings:
+In the example above, there are four bindings and they all provide Python
+implementation functions:
 
 * A binding for a "given a standard setup" step. The binding captures
   no part of the text, and causes the `create_standard_setup` function
@@ -690,7 +704,7 @@ In the example above, there are four bindings:
 * A binding for a "then everything is OK" step, which captures nothing,
   and calls the `check_everything_is_ok` function.
 
-## Simple patterns
+### Simple patterns
 
 The simple patterns are of the form `{name}` and match a single word
 consisting of printable characters. This can be varied by adding a
@@ -711,7 +725,7 @@ Subplot complains if typical regular expression characters are used,
 when simple patterns are expected, unless `regex` is explicitly set to
 false.
 
-## Regular expression patterns
+### Regular expression patterns
 
 Regular expression patterns are used only if the binding `regex` field
 is set to `true`.
@@ -724,9 +738,9 @@ as arguments, when it's called.
 [PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
 [regex]: https://crates.io/crates/regex
 
-## The type map
+### The type map
 
-Patterns may also contain a type map.  This is a dictionary called `types`
+Bindings may also contain a type map.  This is a dictionary called `types`
 and contains a key-value mapping from capture name to the type of the capture.
 Valid types are listed above in the simple patterns section.  In addition to
 simple patterns, the type map can be used for regular expression bindings as
@@ -742,6 +756,32 @@ permits the generated test suites to use native language types directly.  The
 `file` type, if used, must refer to an embedded file in the document; subplot docgen
 will emit a warning if the file is not found, and subplot codegen will emit an error.
 
+### The implementation map
+
+Bindings can contain an `impl` map which connects the binding with zero or more
+language templates.  If a binding has no `impl` entries then it can still be
+used to `docgen` a PDF or HTML document from a subplot document.  This permits a
+workflow where requirements owners / architects design the validations for a
+project and then engineers implement the step functions to permit the
+validations to work.
+
+Shipped with subplot are a number of libraries such as `files` or `runcmd` and
+these libraries are polyglot in that they provide bindings for all supported
+templates provided by subplot.
+
+Here is an example of a binding from one of those libraries:
+
+```yaml
+- given: file {embedded_file}
+  impl:
+    rust:
+      function: subplotlib::steplibrary::files::create_from_embedded
+    python:
+      function: files_create_from_embedded
+  types:
+    embedded_file: file
+```
+
 ### Embedded file name didn't match
 
 ```scenario