👨💻 about me home CV/Resume 🖊️ Contact Github LinkedIn I’m a Haskeller 📝 Blog Freedom, privacy, tutorials… 🏆 Best of Fizzbuzz makex LuaX Calculadoira panda upp Haskell todo pwd TPG Nextcloud Git
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.
DPP is an Open source software. Any body can contribute on GitHub to:
make
.dpp
and gpp
(.exe
files
on Windows) where you want.dpp
require Graphviz
and Java (PlantUML and ditaa are embedded in
dpp
).
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
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.
Diagrams are written in code blocks. The first line contains:
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:
--self-contained
), i.e. the CSS and images are stored
inside the document:
outputpath/img/diag42
[outputpath/]img/diag42
The diagram generator can be:
dpp
will not create any directory, the path where the
image is written must already exist.
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:
dpp
will create a temporary script before calling the
associated interpretor.
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
~~~ bash
# this bash script example won't be executed!
# but only colorized by Pandoc.
~~~
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 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
.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 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 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 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/zsh 5.2.15(1)-release
Here are a few random numbers: 17772, 26794, 1435
Note: the keyword sh
executes
sh
which is generally a link to bash
.
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
)
~~~~~
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:
'm Python 3.11.1 (main, Dec 7 2022, 00:00:00) [GCC 12.2.1 20221121 (Red Hat 12.2.1-4)]
Hi, IHere are a few random numbers: 654, 114, 25
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 8.10
The first 10 prime numbers are: 2 3 5 7 11 13 17 19 23 29
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.jar is integrated in DPP. PlantUML is distributed under the GPL license. See http://plantuml.sourceforge.net/faq.html.
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 is included in the binary distribution of DPP. I have just recompiled the original sources of GPP.
GPP was written by Denis Auroux . Since version 2.12 it has been maintained by Tristan Miller .
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.
Your feedback and contributions are welcome. You can contact me at http://cdsoft.fr