1 files changed, 132 insertions, 8 deletions

diff --git a/subplot.md b/subplot.md
index f16c6fe..ccfc7b4 100644
--- a/subplot.md
+++ b/subplot.md
@@ -1621,25 +1621,149 @@ 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—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:
+
+* no `add-newline` class—default handling: same as `add-newline=auto`
+* `add-newline=auto`—add a newline, if one isn't there
+* `add-newline=no`—never add a newline, but keep one if it's there
+* `add-newline=yes`—always add a newline, even if one is already
+  there
+
+The scenarios below test the various cases. 
+
 ### Extract embedded file
 
-This scenario checks that an embedded file can be extracted.
+This scenario checks that an embedded file can be extracted, and used
+in a subplot.
 
 ~~~scenario
-given file onefile.md
-when I run sp-docgen onefile.md -o onefile.html
-then file onefile.html exists
+given file embedded.md
+when I run sp-docgen embedded.md -o foo.html
+then file foo.html exists
+and file foo.html matches /embedded\.txt/
 ~~~
 
-~~~~{#onefile.md .file .markdown .numberLines}
+~~~~~~~{#embedded.md .file .markdown .numberLines}
 ---
 title: One embedded file
 ...
 
-```{#filename .file}
+~~~{#embedded.txt .file}
 This is the embedded file.
-```
-~~~~
+~~~
+~~~~~~~
+
+
+### Extract embedded file, by default add missing newline
+
+This scenario checks the default handling: add a newline if one is
+missing.
+
+~~~scenario
+given file default-without-newline.txt
+then default-without-newline.txt ends in one newline
+~~~
+
+~~~{#default-without-newline.txt .file .numberLines}
+This file does not end in a newline.
+~~~
+
+
+### Extract embedded file, by default do not add a second newline
+
+This scenario checks the default handling: if content already ends in
+a newline, do not add another newline.
+
+~~~scenario
+given file default-has-newline.txt
+then default-has-newline.txt ends in one newline
+~~~
+
+~~~{#default-has-newline.txt .file .numberLines}
+This file ends in a newline.
+
+~~~
+
+### Extract embedded file, automatically add missing newline
+
+Explicitly request automatic newlines, when the file does not end in
+one.
+
+~~~scenario
+given file auto-without-newline.txt
+then auto-without-newline.txt ends in one newline
+~~~
+
+~~~{#auto-without-newline.txt .file add-newline=auto .numberLines}
+This file does not end in a newline.
+~~~
+
+
+### Extract embedded file, do not automatically add second newline
+
+Explicitly request automatic newlines, when the file already ends in
+one.
+
+~~~scenario
+given file auto-has-newline.txt
+then auto-has-newline.txt ends in one newline
+~~~
+
+~~~{#auto-has-newline.txt .file add-newline=auto .numberLines}
+This file ends in a newline.
+
+~~~
+
+
+### Extract embedded file, explicitly add missing newline
+
+Explicitly request automatic newlines, when the file doesn't end with
+one.
+
+~~~scenario
+given file add-without-newline.txt
+then add-without-newline.txt ends in one newline
+~~~
+
+~~~{#add-without-newline.txt .file add-newline=yes .numberLines}
+This file does not end in a newline.
+~~~
+
+
+### Extract embedded file, explicitly add second newline
+
+Explicitly request automatic newlines, when the file already ends with
+one.
+
+~~~scenario
+given file add-has-newline.txt
+then add-has-newline.txt ends in two newlines
+~~~
+
+~~~{#add-has-newline.txt .file add-newline=yes .numberLines}
+This file ends in a newline.
+
+~~~
+
+
+
+### Extract embedded file, do not add missing newline
+
+Explicitly ask for no newline to be added.
+
+~~~scenario
+given file no-adding-without-newline.txt
+then no-adding-without-newline.txt does not end in a newline
+~~~
+
+~~~{#no-adding-without-newline.txt .file add-newline=no .numberLines}
+This file does not end in a newline.
+~~~
 
 
 ### Fail if the same filename is used twice