From dc2534a5ed2e7b84920338637be513b300e8780f Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Fri, 4 Oct 2019 21:22:40 +0300 Subject: Change: update talk, about ready now --- Makefile | 5 +++ arch.dot | 2 +- echo.md | 17 ++++++++++ echo.png | Bin 0 -> 83473 bytes talk.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++------------- 5 files changed, 110 insertions(+), 23 deletions(-) create mode 100644 echo.md create mode 100644 echo.png diff --git a/Makefile b/Makefile index 84bc9c9..0f1cbd6 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,8 @@ +all: talk.pdf echo.pdf + +echo.pdf: echo.md + pandoc -o echo.pdf echo.md + talk.pdf: talk.md arch.svg pandoc -t beamer -o talk.pdf talk.md diff --git a/arch.dot b/arch.dot index eb82f9c..41cf643 100644 --- a/arch.dot +++ b/arch.dot @@ -14,7 +14,7 @@ digraph "" { codegen [label="Code generator"]; codegen [shape=ellipse]; - pdf [label="PDF document"] + pdf [label="PDF/HTML document"] pdf [shape=diamond]; testprog [label="Test program\n(generated)"] diff --git a/echo.md b/echo.md new file mode 100644 index 0000000..7614bdd --- /dev/null +++ b/echo.md @@ -0,0 +1,17 @@ +--- +title: "**echo**(1) acceptance tests" +... +# Introduction +**echo**(1) is a Unix command line tool, which writes +its command line arguments to the standard output. +This is a simple acceptance test suite for the +`/bin/echo` implementation. + +# No arguments +Run `/bin/echo` without arguments. +```fable +when user runs echo without arguments +then exit code is 0 +and standard output contains a newline +and standard error is empty +``` diff --git a/echo.png b/echo.png new file mode 100644 index 0000000..c5fb0e1 Binary files /dev/null and b/echo.png differ diff --git a/talk.md b/talk.md index 868595f..23b4bb1 100644 --- a/talk.md +++ b/talk.md @@ -4,21 +4,33 @@ author: Lars Wirzenius for the Subplot project date: 2019-10-10 ... - https://subplot.liw.fi/ +Subplot is a set of tools for **specifying** and **documenting** +acceptance criteria for a system or project, and how they should be +**verified**. + +**All stakeholders**, including customers and end-users, should +understand these. +It's not easy. Subplot can't do it alone. You still have to write text +that +everyone understands. + + https://subplot.liw.fi/ --- -Subplot? Let me tell you a story... +Once upon a time there was a king... --- -![](arch.svg) +It all started with yarn in 2013 --- Acceptance criteria are expressed as scenarios (a la Cucumber): +  + _given_ a system in a specific start state _when_ user does some thing _then_ system state has changed in the intended way @@ -26,21 +38,33 @@ _and_ other aspect of state has stayed the same --- -FIXME: Markdown example - +~~~~markdown --- +title: "**echo**(1) acceptance tests" +... +# Introduction +**echo**(1) is a Unix command line tool, which writes +its command line arguments to the standard output. +This is a simple acceptance test suite for the +`/bin/echo` implementation. + +# No arguments +Run `/bin/echo` without arguments. +```fable +when user runs echo without arguments +then exit code is 0 +and standard output contains a newline +and standard error is empty +``` +~~~~ -Currently only docgen exists, codegen will happen soon. - -Docgen = Pandoc + Pandoc filter, in Rust +--- -Filter modifies document during typesetting to make document more -useful for communicating acceptance criteria. Changes how code blocks -with scenario text are presented. +![](echo.png) --- -FIXME: Bindings example +![](arch.svg) --- @@ -53,6 +77,48 @@ Essentially, scenario step is a function call. --- +~~~~yaml +- when: user runs echo without arguments + function: run_echo_without_args + +- when: user runs echo with arguments (?P.+) + function: run_echo_with_args + +- then: exit code is (?P\d+) + function: exit_code_is_zero + +- then: standard output contains a newline + function: stdout_is_a_newline + +- then: standard output contains "(?P.*)" + function: stdout_is_text + +- then: standard error is empty + function: stderr_is_empty +~~~~ + +--- + +Currently only **docgen** exists, work on **codegen** will start soon. + +  + +> docgen = Pandoc + Pandoc filter, in Rust + +  + +Filter modifies document during typesetting to make +document more useful for communicating acceptance +criteria. Typesets scenario text, later maybe other +things. + +Relies on the `pandoc` and `pandoc_ast` crates for +typesetting, `structopt` for command line handling + +Really quite simple + +--- + ~~~~rust use std::path::PathBuf; use structopt::StructOpt; @@ -177,8 +243,7 @@ fn typeset_str(s: &str) -> Inline { --- -The Subplot project is at the very beginning (but Yarn was used for -six years). Help is welcome. +The Subplot project is at the very beginning. Help is welcome. * What do you think of the concept? * What's good? @@ -186,22 +251,22 @@ six years). Help is welcome. * Can you see yourself using it? * What would it take for you to try it? * Do you see Subplot filling a gap for you? +* Can you help with improvements to website, documentation, code? +* Would you be willing to try Subplot in your project? -Expect a working version by the end of the year. Patches are welcome, -but more important now is constructive feedback, especially from -people who use Subplot, or want to. +Expect a working, but primitive version by the end of the year. Patches are welcome, +but more important right now is constructive feedback, especially from +people who use Subplot, or might want to. --- -Free software. +Free software. GPL3+ -Won't affect the licensing of the outputs. OK to use for proprietary -systmes. +Won't affect the licensing of the outputs. OK to use for developing proprietary +systems, but Subplot itself will remain free. --- Thank you ---- - This talk is licensed CC-BY-SA 4.0 (International) -- cgit v1.2.1