Abstract

ppp allows you to use pandoc in new ways by rendering ASCII-markup to beautiful pictures right from within pandoc's verbatim environments.

See below for illustrative examples and detailed usage instructions.

Bonus on top: Leaving out ppp form the typesetting pipeline will still render your document and the verbatims with the ASCII-markup will still stay readable!

General usage

In each case, you will use pandoc's verbatim environment, set the rendering engine and additional options:

~~~~~ {.renderer .option1 .option2=value2}
 --- RENDERER-SPECIFIC MARKUP GOES HERE ---
~~~~~

General Renderers

The renderers available to ppp are:

General Options

This is a list of the general options, compatible with any type of renderer:

ditaa Diagrams

In order to generate ditaa-diagrams, ditaa needs to be installed.

For an exhaustive list of options and possibilities, please check the ditaa homepage.

ditaa Options

Apart from the General Options, the possible options specific to ditaa are:

ditaa Examples

Using ditaa, the following markup will produce Figure .

~~~~~ {.ditaa .rounded-corners .no-shadows
       .scale=90% .title="The ppp and pandoc pipeline"
       .label=fig:pipeline-overview  .no-antialias .no-separation
      } # Caution! These lines actually would have to be on *one* line only!
+-----------------+       +--------+           +--------------------+
| markdown source |------>| ppp    |------*--->| pröcessed markdown |
+-----------------+       +--------+      |    +--------------------+
                              |           \--->| image files        |
                    +------------------+       +--------------------+
                    | diagram creation |
                    +------------------+
                    | ditaa/dot/rdfdot |
                    +------------------+
~~~~~

"The ppp and pandoc pipeline"

"The ppp and pandoc pipeline"

As a contrast, turning off several options, ditaa will produce an output as in Figure :

~~~~~ {.ditaa .scale=90% .title="The ppp and pandoc pipeline #2" .label=fig:pipeline-overview-2}
+-----------------+       +--------+           +--------------------+
| markdown source |------>| ppp    |------*--->| pröcessed markdown |
+-----------------+       +--------+      |    +--------------------+
                              |           \--->| image files        |
                    +------------------+       +--------------------+
                    | diagram creation |
                    +------------------+
                    | ditaa/dot/rdfdot |
                    +------------------+
~~~~~

"The ppp and pandoc pipeline #2"

"The ppp and pandoc pipeline #2"

dot Diagrams

dot rendering is done through GraphViz's engine. Please cf. Graphviz's Documentation for exact usage specifics on the usage of dot.

dot Options

dot Examples

With dot as the renderer, the following markup produces the figure as seen in Figure .

~~~~~ {.dot .scale=50% .title=dot Finite State Automaton .label=fig:dot-fsa}
digraph finite_state_machine {
  rankdir=LR;
  size="8,5"
  node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
  node [shape = circle];
  LR_0 -> LR_2 [ label = "SS(B)" ];
  LR_0 -> LR_1 [ label = "SS(S)" ];
  LR_1 -> LR_3 [ label = "S($end)" ];
  LR_2 -> LR_6 [ label = "SS(b)" ];
  LR_2 -> LR_5 [ label = "SS(a)" ];
  LR_2 -> LR_4 [ label = "S(A)" ];
  LR_5 -> LR_7 [ label = "S(b)" ];
  LR_5 -> LR_5 [ label = "S(a)" ];
  LR_6 -> LR_6 [ label = "S(b)" ];
  LR_6 -> LR_5 [ label = "S(a)" ];
  LR_7 -> LR_8 [ label = "S(b)" ];
  LR_7 -> LR_5 [ label = "S(a)" ];
  LR_8 -> LR_6 [ label = "S(b)" ];
  LR_8 -> LR_5 [ label = "S(a)" ];
}
~~~~~

dot Finite State Automaton

dot Finite State Automaton

neato Diagrams

neato diagrams behave very similarly to dot Diagrams. Please cf dot Diagrams for more information

neato Options

neato Examples

The following example produces Figure .

~~~~~ {.neato .scale=50% .title=neato diagram .label=fig:neato-diagram}
graph G {
  n0 -- n1 -- n2 -- n3 -- n0;
}
~~~~~

neato diagram

neato diagram

yUML

yUML needs a network connection and uses http://yuml.me as the rendering service.

yUML Options

Options specific to yUML can be:

yUML Examples

yUML Class diagrams

With yUML as the renderer, setting .type=class and using the style .style=boring, the following markup produces Figure .

~~~~ {.yuml .style=boring .type=class .direction=TD .title=yUML class diagram .label=fig:yuml-class-diagram}

[Customer] +1 ->        *[Order]
[Order]   ++1 -items>   *[LineItem]
[Order]       -0..1>     [PaymentMethod]
~~~~

yUML class diagram

yUML class diagram

yuml Usecase diagrams

With scruffy style and .type=usecase, the following example produces Figure .

~~~~ {.yuml .style=scruffy .type=usecase .title=yUML usecase diagram .label=fig:yuml-usecase-diagram}
// Cool Use Case Diagram
[Customer]-(Make Cup of Tea)
(Make Cup of Tea)<(Add Milk)
(Make Cup of Tea)>(Add Tea Bag)
~~~~

yUML usecase diagram

yUML usecase diagram

yuml Activity diagrams

Lastly, using .type=activity and .style=plain the following example produces Figure .

~~~~ {.yuml .style=plain .type=activity .title=yUML activity Diagram .label=fig:yuml-activity-diagram}
(start)->|a|,|a|->(Make Coffee)->|b|,|a|->(Make Breakfast)->|b|,|b|-><c>[want more coffee]->(Make Coffee),<c>[satisfied]->(end)
~~~~

yUML activity Diagram

yUML activity Diagram

plantuml

plantuml -- based on graphviz --, has an extensive feature set

plantuml Options

plantuml Examples

plantuml Example 1

With plantuml as the renderer, the following markup produces Figure .

~~~~ {.plantuml}
@startuml
scale 350 width
[*] --> NotShooting

state NotShooting {
  [*] --> Idle
  Idle --> Configuring : EvConfig
  Configuring --> Idle : EvConfig
}

state Configuring {
  [*] --> NewValueSelection
  NewValueSelection --> NewValuePreview : EvNewValue
  NewValuePreview --> NewValueSelection : EvNewValueRejected
  NewValuePreview --> NewValueSelection : EvNewValueSaved

  state NewValuePreview {
     State1 -> State2
  }

}
@enduml
~~~~

PlantUML Example 1

PlantUML Example 1

plantuml Example 2

If the colors don't match your taste exactly, add skinparam monochrome true to retrieve Figure .

~~~~ {.plantuml}
@startuml

skinparam monochrome true

actor User
participant "First Class" as A
participant "Second Class" as B
participant "Last Class" as C

User -> A: DoWork
activate A

A -> B: Create Request
activate B

B -> C: DoWork
activate C
C --> B: WorkDone
destroy C

B --> A: Request Created
deactivate B

A --> User: Done
deactivate A

@enduml
~~~~

PlantUML Example 2

PlantUML Example 2

rdfdot Diagrams

rdfdot Options

rdfdot Examples

The following example produces Figure on page .

~~~~~ {.rdfdot .scale=65% .title=rdfdot Diagram .label="fig:rdfdot-diagram"}

@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@base <http://example.com/> .
<alice> foaf:name "Alice" ;
        foaf:knows [ foaf:name "Bob" ] .
~~~~~

rdfdot Diagram

rdfdot Diagram

List of options

List of options
Renderer Option possible values
General .scale 1%--99%
.label fig:my-figure
.title "Some label for the figure"
ditaa .rounded-corners
.no-shadows
.no-antialias
.no-separation
dot N/A
neato N/A
yUML .type= any of [ class, activity, usecase ]
.style= any of [ scruffy, boring, plain ]
.direction= any of [ LR, RL, TD, ]
rdfdot N/A

List of homepages and documentation to renderers

List of options
Renderer Links
ppp (this document)
https://metacpan.org/release/App-pandoc-preprocess
https://github.com/xdbr/p5-App-pandoc-preprocess
ditaa http://ditaa.sourceforge.net/
dot http://www.graphviz.org/
neato http://www.graphviz.org/
yUML http://yuml.me/
https://github.com/wandernauta/yuml
rdfdot https://metacpan.org/pod/RDF::Trine::Exporter::GraphViz
plantuml http://plantuml.sourceforge.net/

Credits and further references