Ditaa Code Blocks in Org

Org support for ditaa

Introduction

Ditaa is a command-line utility that converts diagrams drawn using ASCII art into bitmap graphics.

Requirements and Setup

Ditaa is no longer distributed with Org. Now, you will need to install ditaa and store the path to the executable in the variable ob-ditaa-jar-path. Often, this is all that is needed to set up ditaa in Babel. Nevertheless, Org offers several other variables designed to accommodate non-standard Java setups. These include org-babel-ditaa-java-cmd, org-ditaa-eps-jar-path, and org-ditaa-jar-option.

Activate evaluation of ditaa source code blocks by adding ditaa to org-babel-load-languages.

(org-babel-do-load-languages
 'org-babel-load-languages
 '((ditaa . t))) ; this line activates ditaa

Customization Options

Org needs to know a few things about ditaa and the java executable in order to function. The following is a list of variables that can be customized.

org-ditaa-jar-path: The path to the ditaa jar file.
org-babel-ditaa-java-cmd: The name or path to the Java executable used to run the ditaa jar file.
org-ditaa-eps-jar-path: The path to the ditaaeps jar file. DitaaEps is maintained as part of the ditaa-addons project.
org-ditaa-jar-option: The prefix used before the ditaa jar path. The default is -jar.

Babel Features for ditaa Code Blocks

Header Arguments

file: the output filename (mandatory)
cmdline: command line arguments for ditaa
java: arguments for the java runtimes (JRE)
eps: produce an eps output file using ditaaeps
pdf: produce a pdf output file using ditaaeps followed by epstopdf

Sessions

Ditaa does not support sessions.

Result Types

Ditaa produces a png bitmap file by default. See the header arguments, eps and pdf, for alternative file formats.

Examples of Use

Hello World

Here is the obligatory Hello World! example in ditaa.

#+NAME: hello-world
#+BEGIN_SRC ditaa :file images/hello-world.png
+--------------+
|              |
| Hello World! |
|              |
+--------------+
#+END_SRC

Figure 1: The graphic produced by `hello-world`.

Passing command-line options to `ditaa`

Now, round all corners by passing ditaa the -r,--round-corners command line switch.

#+NAME: hello-world-round
#+BEGIN_SRC ditaa :file images/hello-world-round.png :cmdline -r
+--------------+
|              |
| Hello World! |
|              |
+--------------+
#+END_SRC

Figure 2: The graphic produced by `hello-world-round`.