diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-12-09 17:44:22 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-12-10 09:07:10 +0200 |
commit | 72930a10d5aea6f57e4ba115f82b2dacc1faf6f6 (patch) | |
tree | 9894cd62c7ffcfae5cb64a937ec56688cd3a73d2 | |
parent | 10bce17b699bdcc90b87b1eb829693bf92d08d73 (diff) | |
download | pandoc-filter-diagram-72930a10d5aea6f57e4ba115f82b2dacc1faf6f6.tar.gz |
test: add subplot file for verifying that the binary works
Sponsored-by: author
-rw-r--r-- | pandoc-filter-diagram.md | 254 |
1 files changed, 254 insertions, 0 deletions
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 +~~~ +~~~~~~~~ |