Sequence diagrams with VIM and PlantUML

Today I needed to sketch out some ideas on how to model a process.
I've found that simple sequence diagrams are often useful to visualize how a process flows. Combined with the mighty tools that are paper and pencil I can quite quickly grasp the structure of an otherwise abstract idea.

Going digital

Some times though, the paper and pencil approach comes to short.
This could be because I need to work on an idea over a longer period of time. Or it could be because the diagram is rather complicated and I find myself changing large parts of it. The result either way is that the diagram gets really cluttered, and so loses its ability to help me structure my thoughts.
And this is when moving to a digital tool can help.
There's no shortage of diagram creation tools out there, but I've found that the majority takes too much effort to use efficiently. The result is that I spend more time thinking about how I use the tool rather than the idea I'm sketching out. I'm sure those tools have their place too, but it's probably not quick sketching and structuring of ideas.

Keeping it simple

The one tool I have found that I can work efficiently with is PlantUML. PlantUML is a java based tool that in its essence lets you describe a diagram in structured text that the software rendres to an image.

@startuml img/sequence_img001.png
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response

and the result looks like this:
The real beuty of it is that I can make sense of the text without the image. Also I'm a lot faster at typing and editing text than I am at pointing and clicking and dragging in a diagram editor.


There are a lot of integrations and editors that let you make PlantUML diagrams. But I've found that since the main activity is editing text, using my favourite text editor VIM is the most comfortable and efficient.

You can just fire up PlantUML and have it monitor the directory where your diagram definition files are located and it will periodically update the images when the definitions change.

But where's the fun in that

As a geek I found that having to fire up a second piece of software, and then maybe wait a bit for it to pick up the changes was a bit unsatisfying.
And as other vim users are probably even more geeky than me, there was of course a solution:
Anders Thøgersen has made not just a syntax definition file for the PlantUML syntax, but also a plugin that create a vim :make command that when run will activate PlantUML and generate the image instantly. The entire package is to be found at github:

The plugin needs some tweeking to work, and here's how mine looks:
After being corrected by Anders in the comments below, there is no need to edit the plugin script to set the correct executable path.

" Language:     PlantUML
" Maintainer:   Aaron C. Meadows &lt; language name at shadowguarddev dot com&gt;
" Last Change:  19-Jun-2012
" Version:      0.1

if exists("g:loaded_plantuml_plugin")
let g:loaded_plantuml_plugin = 1

if !exists("g:plantuml_executable_script")
        let g:plantuml_executable_script='java -jar c:\utils\plantuml\plantuml.jar'
let s:makecommand=g:plantuml_executable_script." %"

" define a sensible makeprg for plantuml files
autocmd Filetype plantuml let &l:makeprg=s:makecommand

I only changed the line where the executable is assigned. The original referenced a bash script that I can't make on my windows machine.
The path of the executable can be set in your .vimrc file and the plugin script will respect that path.
Add the following line to your .vimrc file to set the correct executable for you system:

let g:plantuml_executable_script='java -jar c:\utils\plantuml\plantuml.jar'

Note: Make sure the java executable is in your path.

To add some icing to the top I created a keybinding for :make to the familiar F5 button.
I did this by adding the followin lines to my vimrc file:

nnoremap <F5> :w<CR> :silent make<CR>
inoremap <F5> <Esc>:w<CR>:silent make<CR>
vnoremap <F5> :<C-U>:w<CR>:silent make<CR

I added the :w before the :make to make sure the file got saved so that PlantUML can read it.

Now I just open the image on one screen, edit in VIM on the other, press F5 and purr with satisfaction as I watch the image update instantly.

A little word of caution at the end:
I am a complete newb to vim scripting and customization, and as such my code hereour could potentially be really bad.