Using dot from graphviz

The whole graphviz package is an amazingly useful piece of software.  Especially the dot program.

I've watched other people hand-craft Visio documents that go out of date really fast.

I've also watched developers try to use design tools for high-level sketch kind of diagrams and get bogged down with superfluous code-sync features.

When I want to illustrate a point, just plain old boxes and arrows work wonders.  Especially when I can commit the source and be able to tweak it afterwards.

I've found that dot meets and exceeds the my common use goals.  I would guess that 80% of the time, the diagram communicates what I want to say without any tweaking at all.  About 15% of the time, it takes some layout/shape/font/color tweaking to get the message across in a clear & direct manner.  About 5% of the time, I have to output the graph as SVG and load it into Inkscape for further slight tweaking.

Here are some especially helpful links:

• official site
• gallery of examples, also 
• up-to-date language reference, and other documentation
• outdated, but very well-organized Users Guide
• dot-functions.sh

The last piece of software is intended as a helper for invoking dot quickly from the command line as part of a REPL authoring flow.

To use dot-functions.sh, first download it.  The script defines a bash function that can be used from a bash CLI.  Source it into the current shell by doing: source dot-functions.sh, followed by dot somefile.dot.


Here is the source of dot-functions.sh:

	#!/bin/bash
	echo $0 | grep -q "dot-functions.sh" && {
	echo "usage: source dot-functions.sh, then run 'dot foo.dot' and the PNG will show"
	exit 1
	}
	produce_image_type() {
	for arg in "$@"; do
	[[ "$arg" =~ -T[-_a-z]+ ]] && echo ${arg#-T} && return 0
	done
	echo "png"
	}
	dot() {
	local DOT_CMD=`which dot`
	local IMAGE_TYPE=`produce_image_type "$@"`
	for f in "$@"; do
	[[ "$f" =~ -T[-_a-z]+ ]] && continue
	# strip trailing ".dot"
	# NOTE: also handle trailing ".", which is what happens when you
	# tab-complete after the png already exists
	EXT=`echo $f | grep -o '[^.]*$'` # usually just "dot", but some people call dot files .gv
	FILE=`echo $f | sed -e 's/\.[^.]*$//' -e 's/\.$//'`
	$DOT_CMD -T$IMAGE_TYPE "$FILE.$EXT" > "$FILE.$EXT.$IMAGE_TYPE" && local IMAGE_FILES="$IMAGE_FILES \"$FILE.$EXT.$IMAGE_TYPE\"" || return 1
	done &&
	if [[ `uname -a` =~ "Darwin" ]]
	then
	eval "open $IMAGE_FILES"
	else
	eval "gnome-open $IMAGE_FILES"
	fi
	}

view raw dot-functions.sh hosted with ❤ by GitHub

Another very helpful article was written on this topic by Diomidis Spinellis.  Now that I think about it, there is another very helpful article about how to get a hand-written sketch into digital form.