# 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:

- ditaa
- yuml diagrams:
  - class diagramas (cf. Figure )
  - usecase diagramas (cf. Figure )
  - activity diagramas (cf. Figure )
- dot
- neato
- rdfdot
- plantuml

## General Options

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

- `.scale=90%`
- `.label=fig:my-figure`
- `.title="Some label for the figure"`

# 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:

- `.rounded-corners`
- `.no-shadows`
- `.no-antialias`
- `.no-separation`

## 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"

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"

# 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

- currently none apart from the General 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

# neato Diagrams

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

## neato Options

- same as dot 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

# yUML

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

## yUML Options

Options specific to yUML can be:

- `.type=`: any of `[` `class`, `activity`, `usecase` `]`
- `.style=`: any of `[` `scruffy`, `boring`, `plain` `]`
- `.direction=`: any of `[` `LR`, `RL`, `TD`, `]`

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

# plantuml

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

## plantuml Options

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

# rdfdot Diagrams

## rdfdot Options

- currently none apart from the General 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

# 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

- http://www.asciiflow.com/#Draw: an excellent helper for all things diagram
- http://randomdeterminism.wordpress.com/2012/06/01/how-i-stopped-worring-and-started-using-markdown-like-tex/: general introduction to another approach to typesetting and using `gpp`
- https://github.com/nichtich/ditaa-markdown: This is where the original idea came from
- gpp: http://files.nothingisreal.com/software/gpp/gpp.html