From 72930a10d5aea6f57e4ba115f82b2dacc1faf6f6 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Thu, 9 Dec 2021 17:44:22 +0200 Subject: test: add subplot file for verifying that the binary works Sponsored-by: author --- pandoc-filter-diagram.md | 254 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 pandoc-filter-diagram.md diff --git a/pandoc-filter-diagram.md b/pandoc-filter-diagram.md new file mode 100644 index 0000000..86081d4 --- /dev/null +++ b/pandoc-filter-diagram.md @@ -0,0 +1,254 @@ +--- +title: pandoc-filter-diagram +subtitle: Acceptance criteria +author: Lars Wirzenius +template: rust +bindings: +- lib/files.yaml +- lib/runcmd.yaml +- subplot/subplot.yaml +functions: +- subplot/subplot.rs +... + +# Introduction + +This document specifies the acceptance criteria for +`pandoc-filter-diagram`, and how they are verified. It's meant to be +processed with the [Subplot](https://subplot.liw.fi/) tool. The +`build.rs` script makes sure the verification scenarios defined here +are run when `cargo test` is run. + +The code in `pandoc-filter-diagram` was originally part of Subplot. It +was extracted into its own crate for use in the [Sequoia][] sq user guide. + +[Sequoia]: https://sequoia-pgp.org/ + + +# Pikchr + +[Pikchr]: https://pikchr.org/ + +[Pikchr] is a diagramming library which implements a Pic-like diagram language. +It allows the conversion of textual descriptions of arbitrarily complex diagrams +into SVGs such as this one. + +~~~pikchr +arrow right 200% "Markdown" "Source" +box rad 10px "Subplot" "Document Generator" "(subplot docgen)" fit +arrow right 200% "HTML+SVG/PDF" "Output" +arrow <-> down 70% from last box.s +box same "Pikchr" "Formatter" "(docs.rs/pikchr)" fit +~~~ + +This scenario checks that an image is generated and embedded into the HTML output, +and is not referenced as an external image. + +~~~scenario +given an installed Rust program pandoc-filter-diagram +given file pikchr.md +when I run pandoc --filter subplot-filter pikchr.md -o pikchr.html +then file pikchr.html matches regex /img src="data:image/svg\+xml;base64,/ +~~~ + +~~~~~~~~{#pikchr.md .file .markdown .numberLines} +This is an example markdown file that embeds a simple Pikchr diagram. + +~~~pikchr +arrow right 200% "Markdown" "Source" +box rad 10px "Markdown" "Formatter" "(docs.rs/markdown)" fit +arrow right 200% "HTML+SVG" "Output" +arrow <-> down 70% from last box.s +box same "Pikchr" "Formatter" "(docs.rs/pikchr)" fit +~~~ +~~~~~~~~ + + + +# Graphviz Dot + +[Graphviz]: http://www.graphviz.org/ + +Dot is a program from the [Graphviz][] suite to generate directed +graphs, such as this one. + +~~~dot +digraph "example" { +thing -> other +} +~~~ + +The scenario checks that an image is generated and embedded into the +HTML output, not referenced as an external image. + +~~~scenario +given an installed Rust program pandoc-filter-diagram +given file dot.md +when I run pandoc --filter subplot-filter dot.md -o dot.html +then file dot.html matches regex /img src="data:image/svg\+xml;base64,/ +~~~ + +~~~~~~~~{#dot.md .file .markdown .numberLines} +This is an example Markdown file, which embeds a graph using dot markup. + +~~~dot +digraph "example" { +thing -> other +} +~~~ +~~~~~~~~ + + + +# PlantUML + +[PlantUML]: https://plantuml.com/ + +[PlantUML][] is a program to generate various kinds of UML diagrams +for describing software, such as this one: + +~~~plantuml +@startuml +Alice -> Bob: Authentication Request +Bob --> Alice: Authentication Response + +Alice -> Bob: Another authentication Request +Alice <-- Bob: Another authentication Response +@enduml +~~~ + +The scenario below checks that an image is generated and embedded into +the HTML output, not referenced as an external image. + +~~~scenario +given an installed Rust program pandoc-filter-diagram +given file plantuml.md +when I run pandoc --filter subplot-filter plantuml.md -o plantuml.html +then file plantuml.html matches regex /img src="data:image/svg\+xml;base64,/ +~~~ + +~~~~~~~~{#plantuml.md .file .markdown .numberLines} +This is an example Markdown file, which embeds a diagram using +PlantUML markup. + +~~~plantuml +@startuml +Alice -> Bob: Authentication Request +Bob --> Alice: Authentication Response + +Alice -> Bob: Another authentication Request +Alice <-- Bob: Another authentication Response +@enduml +~~~ +~~~~~~~~ + + + +# Roadmap + +[roadmap]: https://crates.io/crates/roadmap + +The [roadmap][] Rust library supports visual roadmaps using a YAML +based markup language. + +An example: + +~~~roadmap +goal: + label: | + This is the end goal: + if we reach here, there + is nothing more to be + done in the project + depends: + - finished + - blocked + +finished: + status: finished + label: | + This task is finished; + the arrow indicates what + follows this task (unless + it's blocked) + +ready: + status: ready + label: | + This task is ready + to be done: it is not + blocked by anything + +next: + status: next + label: | + This task is chosen + to be done next + +blocked: + status: blocked + label: | + This task is blocked + and can't be done until + something happens + depends: + - ready + - next +~~~ + +This scenario checks that an image is generated and embedded into the +HTML output, not referenced as an external image. + +~~~scenario +given an installed Rust program pandoc-filter-diagram +given file roadmap.md +when I run pandoc --filter subplot-filter roadmap.md -o roadmap.html +then file roadmap.html matches regex /img src="data:image/svg\+xml;base64,/ +~~~ + +~~~~~~~~{#roadmap.md .file .markdown .numberLines} +This is an example Markdown file, which embeds a roadmap. + +~~~roadmap +goal: + label: | + This is the end goal: + if we reach here, there + is nothing more to be + done in the project + depends: + - finished + - blocked + +finished: + status: finished + label: | + This task is finished; + the arrow indicates what + follows this task (unless + it's blocked) + +ready: + status: ready + label: | + This task is ready + to be done: it is not + blocked by anything + +next: + status: next + label: | + This task is chosen + to be done next + +blocked: + status: blocked + label: | + This task is blocked + and can't be done until + something happens + depends: + - ready + - next +~~~ +~~~~~~~~ -- cgit v1.2.1