DPP - Diagram preprocessor (with pandoc in mind)

Initially, the PP package contained three preprocessors for Pandoc.

I started using Markdown and Pandoc with GPP. Then I wrote DPP to embed diagrams in Markdown documents. And finally PP which merges the functionalities of GPP and DPP.

GPP and DPP are not included anymore in PP as pp can be used standalone.

DPP just contains dpp itself as well as GPP.

dpp is obsolete, please consider using PP instead.

Open source

DPP is an Open source software. Any body can contribute on GitHub to:

• suggest or add new functionalities
• report or fix bugs
• improve the documentation
• add some nicer examples
• find new usages
• …

Installation

1. Download and extract dpp.tgz.
2. Run make.
3. Copy dpp and gpp (.exe files on Windows) where you want.

dpp require Graphviz and Java (PlantUML and ditaa are embedded in dpp).

Usage

dpp is a filter and has no options. It takes some text with embedded diagrams on stdin and generates a text with image links on stdout. Some error messages may be written to stderr.

Being a filter, dpp can be chained with other preprocessors. Another good generic purpose preprocessor is pp or gpp.

A classical usage of dpp along with gpp and Pandoc is:

For instance, on any good Unix like system, you can use this command:

$ gpp documents... | dpp | pandoc -f markdown -t html5 -o document.html

Design

dpp was initially a preprocessor for GraphViz diagrams. It now also comes with PlantUML, ditaa and scripting capabilities. dpp requires GraphViz and Java to be installed, PlantUML and ditaa are embedded in dpp.

Optionally, dpp can call Bash, Bat, Python or Haskell to execute general scripts.

Syntax

Diagrams

Diagrams are written in code blocks. The first line contains:

• the diagram generator
• the image name (without the extension)
• the legend (optional)

Block delimiters are made of three or more tilda or back quotes, at the beginning of the line (no space and no tab). Both lines must have the same number of tilda or back quotes.

~~~~~ dot path/imagename optional legend
graph {
    "source code of the diagram"
}
~~~~~

This extremely meaningful diagram is rendered as path/imagename.png and looks like:

The image link in the output markdown document may have to be different than the actual path in the file system. This happens when then .md or .html files are not generated in the same path than the source document. Brackets can be used to specify the part of the path that belongs to the generated image but not to the link in the output document. For instance a diagram declared as:

~~~~~ dot [mybuildpath/]img/diag42
...
~~~~~

will be actually generated in:

mybuildpath/img/diag42.png

and the link in the output document will be:

img/diag42.png

For instance, if you use Pandoc to generate HTML documents with diagrams in a different directory, there are two possibilities:

1. the document is a self contained HTML file (option --self-contained), i.e. the CSS and images are stored inside the document:
   • the CSS path shall be the actual path where the CSS file is stored
   • the image path in diagrams shall be the actual path where the images are stored (otherwise Pandoc won’t find them)
   • e.g.: outputpath/img/diag42
2. the document is not self contained, i.e. the CSS and images are stored apart from the document:
   • the CSS path shall be relative to the output document
   • the image path in diagrams shall be relative to output document in HTML links and shall also describe the actual path where the images are stored.
   • e.g.: [outputpath/]img/diag42

The diagram generator can be:

• dot
• neato
• twopi
• circo
• fdp
• sfdp
• patchwork
• osage
• uml
• ditaa

dpp will not create any directory, the path where the image is written must already exist.

Scripts

Scripts are also written in code blocks. The first line contains only the kind of script.

~~~~~ bash
echo Hello World!
~~~~~

With no surprise, this script generates:

Hello World!

The script language can be:

• bash (or sh)
• bat (DOS/Windows batch language)
• python
• haskell

dpp will create a temporary script before calling the associated interpretor.

Verbatim copy

Blocks can also contain verbatim text that is preserved in the output.

`````````` quote
~~~ bash
# this bash script example won't be executed!
# but only colorized by Pandoc.
~~~
``````````

becomes

# this bash script example won't be executed!
# but only colorized by Pandoc.

Examples

The source code of this document contains some diagrams.

Here are some simple examples. For further details about diagrams’ syntax, please read the documentation of GraphViz, PlantUML and ditaa.

Graphviz

GraphViz is executed when one of these keywords is used: dot, neato, twopi, circo, fdp, sfdp, patchwork, osage

~~~~~ twopi doc/img/dpp-graphviz-example This is just a GraphViz diagram example
digraph {
    O -> A
    O -> B
    O -> C
    O -> D
    D -> O
    A -> B
    B -> C
    C -> A
}
~~~~~

• twopi is the kind of graph (possible graph types: dot, neato, twopi, circo, fdp, sfdp, patchwork).
• doc/img/dpp-graphviz-example is the name of the image. dpp will generate doc/img/dpp-graphviz-example.dot and doc/img/dpp-graphviz-example.png.
• the rest of the first line is the legend of the graph.
• other lines are written to doc/img/dpp-graphviz-example.dot before running Graphviz.

You can use dpp in a pipe before Pandoc (as well as pp or gpp) for instance):

pp file.md | dpp | pandoc -s -S --self-contained -f markdown -t html5 -o file.html

or

cat file.md | gpp -T -x | dpp | pandoc -s -S --self-contained -f markdown -t html5 -o file.html

Once generated the graph looks like:

GraphViz must be installed.

PlantUML

PlantUML is executed when the keyword uml is used. The lines startuml and enduml required by PlantUML are added by dpp.

~~~~~ uml doc/img/dpp-plantuml-example This is just a PlantUML diagram example
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
~~~~~

Once generated the graph looks like:

PlantUML is written in Java and is embedded in dpp. Java must be installed.

Ditaa

ditaa is executed when the keyword ditaa is used.

~~~~~ ditaa doc/img/dpp-ditaa-example This is just a Ditaa diagram example
    +--------+   +-------+    +-------+
    |        | --+ ditaa +--> |       |
    |  Text  |   +-------+    |diagram|
    |Document|   |!magic!|    |       |
    |     {d}|   |       |    |       |
    +---+----+   +-------+    +-------+
        :                         ^
        |       Lots of work      |
        +-------------------------+
~~~~~

Once generated the graph looks like:

ditaa is written in Java and is embedded in dpp. Java must be installed.

Bash

Bash is executed when the keyword bash is used.

~~~~~ bash
echo "Hi, I'm $SHELL $BASH_VERSION"
RANDOM=42 # seed
echo "Here are a few random numbers: $RANDOM, $RANDOM, $RANDOM"
~~~~~

This script outputs:

Hi, I'm /bin/bash 4.3.30(1)-release
Here are a few random numbers: 17766, 11151, 23481

Note: the keyword sh executes sh which is generally a link to bash.

Bat

Bat is executed when the keyword bat is used.

~~~~~ bat
echo Hi, I'm %COMSPEC%
ver
if not "%WINELOADER%" == "" (
    echo This script is run from wine under Linux
) else (
    echo This script is run from a real Windows
)
~~~~~

This script outputs:

Hi, I'm C:\windows\system32\cmd.exe

Wine CMD version 5.1.2600 (1.6.2)
This script is run from wine under Linux

Python

Python is executed when the keyword python is used.

~~~~~ python
import sys
import random

if __name__ == "__main__":
    print("Hi, I'm Python %s"%sys.version)
    random.seed(42)
    randoms = [random.randint(0, 1000) for i in range(3)]
    print("Here are a few random numbers: %s"%(", ".join(map(str, randoms))))
~~~~~

This script outputs:

Hi, I'm Python 2.7.9 (default, Mar  1 2015, 12:57:24) 
[GCC 4.9.2]
Here are a few random numbers: 640, 25, 275

Haskell

Haskell is executed when the keyword haskell is used.

~~~~~ haskell
import System.Info
import Data.Version
import Data.List

primes = filterPrime [2..]
    where filterPrime (p:xs) =
            p : filterPrime [x | x <- xs, x `mod` p /= 0]

version = showVersion compilerVersion
main = do
    putStrLn $ "Hi, I'm Haskell " ++ version
    putStrLn $ "The first 10 prime numbers are: " ++
                intercalate " " (map show (take 10 primes))
~~~~~

This script outputs:

Hi, I'm Haskell 7.10
The first 10 prime numbers are: 2 3 5 7 11 13 17 19 23 29

Licenses

PP/DPP

Copyright (C) 2015, 2016 Christophe Delord
http://www.cdsoft.fr/dpp

DPP is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

DPP is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with DPP. If not, see http://www.gnu.org/licenses/.

PlantUML

PlantUML.jar is integrated in DPP. PlantUML is distributed under the GPL license. See http://plantuml.sourceforge.net/faq.html.

ditaa

ditaa.jar is integrated in DPP. ditaa is distributed under the GNU General Public License version 2.0 (GPLv2). See http://sourceforge.net/projects/ditaa/.

GPP

GPP is included in the binary distribution of DPP. I have just recompiled the original sources of GPP.

GPP was written by Denis Auroux <aurouxmath.mit.edu>. Since version 2.12 it has been maintained by Tristan Miller <psychonautnothingisreal.com>.

Copyright (C) 1996-2001 Denis Auroux.
Copyright (C) 2003, 2004 Tristan Miller.

Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and this permission notice are preserved, thus giving the recipient permission to redistribute in turn.

Permission is granted to distribute modified versions of this document, or of portions of it, under the above conditions, provided also that they carry prominent notices stating who last changed them.

Feedback

Your feedback and contributions are welcome. You can contact me at http://cdsoft.fr