Felix Codes

Notes on diagramming languages

I'm a text-oriented person, but sometimes a picture really is worth a thousand words. Problem is, diagramming software is often slow and clumsy. And it's more precise to generate diagrams from a textual description anyway. Talk about coming full circle.


GraphViz is an old, established tool for automatically drawing diagrams with fairly complex layout from a textual description. In other words to make this:

Diagram of five oval nodes with arrows between them forming an X shape, labeled from A to E.

out of this:

digraph {
	A -> B -> C
	D -> B -> E

It supports half a dozen or more layout engines, dozens of output formats and numerous formatting options, including various shapes, fonts and colors, as well as hyperlinks.


A much newer tool, Pikchr is the latest take on a mature concept. Also much simpler, it's optimized for diagrams like this one:

Diagram of the steps taken by a compiler toolchain to produce executables from source code.

Which can be obtained from the description below:

arrow "source" "code"
box "preprocessor"
arrow "program" "text"
box "compiler"
arrow "assembly" "language"
box "assembler"
arrow "object" "code"
box "linker"
arrow "executable" "program"

Pikchr doesn't do auto-layout, but has some tricks up its sleeve anyway. For a more complex layout, you can first place the boxes, then draw the arrows:

Diagram showing four boxes arranged in a square, with crossing diagonal arrows between them.

Which can be written in a surprisingly natural style:

A: box "A"; move; B1: box "B'"
down; move; A1: box "A'"
left; move; B: box "B"
arrow from A.se to A1.nw
arrow from B.ne to B1.sw

Pikchr can only output SVG, but is very small, fast and portable. Otherwise it also supports fonts, colors and the like, along with a rich language for manual layout.


A more specialized language, but otherwise surprisingly similar, is Zinnia, by David Welbourn. It works on a spreadsheet-like principle, and has a number of unique features. On the other hand version 3 only renders to an HTML5 canvas, via JS.

You can see a sample of my own on the City of Dead Leaves homepage.

Last modified: