---
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
~~~
~~~~~~~~