From d8eb94901bd66e77e4366a29b67c71db934fadf9 Mon Sep 17 00:00:00 2001
From: Daniel Silverstone <dsilvers@digital-scurf.org>
Date: Wed, 4 May 2022 20:20:07 +0100
Subject: (subplot.md): Add example scenarios covering example blocks

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>
---
 subplot.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

(limited to 'subplot.md')

diff --git a/subplot.md b/subplot.md
index 3d4fb91..d7a6c29 100644
--- a/subplot.md
+++ b/subplot.md
@@ -2779,6 +2779,63 @@ This is the embedded file.
 ```
 ~~~~
 
+## Example blocks
+
+Similar to embedded files, Subplot permits you to mark blocks as examples.
+Example blocks are formatted just like file blocks, but they may not be
+used by scenarios and their names are separated from files, and are not
+subject to the same naming constraints (caseless uniqueness).
+
+### Examples may be unused
+
+~~~scenario
+given file unusedexample.md
+and an installed subplot
+when I try to run subplot docgen --merciful unusedexample.md -o unusedexample.html
+then command is successful
+and file unusedexample.html exists
+and stderr doesn't contain "thisisnotused.txt"
+~~~
+
+~~~{#unusedexample.md .file .markdown .numberLines}
+---
+title: Example is not an embedded file
+...
+
+```{#thisisnotused.txt .example}
+This is the embedded example.
+```
+~~~
+
+### Examples are not files
+
+~~~scenario
+given file examplesnotfiles.md
+and an installed subplot
+when I try to run subplot codegen examplesnotfiles.md -t python -o examplesnotfiles.html
+then command fails
+and file examplesnotfiles.html does not exist
+and stderr contains "thisisanexample.txt"
+~~~
+
+~~~{#examplesnotfiles.md .file .markdown .numberLines}
+---
+title: Examples are not files
+impls:
+  python: []
+...
+
+# Try and use an example as a file
+
+```scenario
+given file thisisanexample.txt
+```
+
+```{#thisisanexample.txt .example}
+This is an embedded example
+```
+
+~~~
 
 ## Steps must match bindings
 
-- 
cgit v1.2.1