Syntactic Sugar

ORG MODE is great for writing documents, and its flexibility when it comes to exporting means writing documentation is a snap. There is a limitation, however - producing diagrams often requires the dreaded application switch. Org-babel is a literate programming parser for org files. We looked at Org-babel's tangler in a previous blog post. There we took a file which combined a descriptive document and source code, with the intent of extracting the code and running it. Now we are going to execute source code in line. Org-babel proudly supports a large number of languages. Seriously, look into it Today we're going to start with something simple. Ditaa (DIagrams Through Ascii Art) is a command line diagram parser - it takes a Ascii representation of a diagram as an input, and spits out a image of the diagram as an output. There's some nice support for Ditaa baked in to org-babel, but some tweaking is required. Lets jump in.

According to the Ditaa documentation, the program should be included with org, and the default variables in org-babel seem to agree with this, but I couldn't find it. I'm guessing it's one of those Emacs package version bits of weirdness. So our first task is to get the Ditaa jar file. I am specific about needing the jar file, as I tried installing Ditaa using homebrew, but that version comes with a commandline executable, which did not appear to play nice with org-babel. Download Ditaa from here and put the jar file somewhere safe. When using org-babel, we are essentially giving the parser permission to execute arbitrary code, and all the scary security implications which go with that. Org-babel requires you to explicitly enable a language in order to execute code in that language. Open your emacs config file, and add the following elisp code:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((ditaa . t))
)

This adds ditaa to the list of allowed languages. You'll also need to let org know where your Ditaa jar file is. Add this to your config as well:

(setq org-ditaa-jar-path "/path/to/jar/ditaa.jar")

Naturally, substituting the path with where you placed the downloaded jar file earlier.