Dot... and Dotty

As a developer, one of the things I constantly do is documentation. This is not exactly a favorite task of mine, but I know it's a necessary evil. My programs are typically commented generously. Where necessary I create separate technical documents as well.

In order to make this mundane task a little more interesting, I always try to find tools to help with documentation. For e.g., I found Cppdoc, to document C++ programs, (similar to Javadoc), couple of years ago. While researching on this, I stumbled on Dotty. I found a great tool called GraphViz, but  I didn't do much with it at the time.

Recently when I had a need to create a flowchart for a work flow, again I looked for some tools. I could have used Visio and created some diagrams, but I wanted to automate the process of creating diagrams based on some (text) input. While researching, I re-discovered Dot and Dotty!

DOT and Dotty were originally developed by AT&T Bell Labs. DOT is a plain text graph description language. It's a definition language like CSS.  We can simply type up the information about a graph in human readable Text format, then feed it to a tool to generate a visual graph in various graphic formats. Dotty is a graph editor. AT&T actually bundled dotty and other tools as Graphviz. Graphviz is a collection of tools that interpret Dot structures and generate Graphs in various layouts.

In Dot language, Graphs can be defined as directed (DiGraph) or undirected (Graph). It also defines various elements in a graph such as nodes, arrows/lines or edges, labels etc. The syntax for the language includes various attributes of these elements as well. Thus by combining these elements and their attributes, one can build complex graphs/charts. Examples of such diagrams include, database schema diagrams, network nodes and connections, flow charts etc. The tools are capable of generating the diagrams in various graphic formats including JPG, PNG and SVG. A diagram is created in SVG format can be read by visio and other tools, thus sharing is easier.

The specification for DOT language is simple:

For e.g.,

graph {
a--b--c
}
Will generate

Each circle there is a node and the lines (with or without arrows) are called edges. Each of these have several attributes which can be used to control the presentation and to some extent actual layout.

Below is a simple directional graph (lines with arrows):

digraph{A->B->C->A}

Following line creates a yellow colored oval node:

n[style=filled color="red" fillcolor="yellow"]

The same node as a rectangle:
n[shape=rectangle style=filled color="red" fillcolor="yellow"]



There are several other attributes that can be used to build really complex diagrams. See here for syntax. References listed at the bottom have more details.

The strength of Dot is that the language is small and text-based. Thus, we can write scripts or programs to generate such a text description of a graph. One such application would be to generate graphical calling tree for programs.

Dotty and other tools in Graphviz bundle all have similar command line syntax. A typical usage would be,

 

dot -O -Tpng <example.dot>

I found a great use for this tool, recently. At work, we have sort of a workflow system. The system keeps track of various types of Cases generated by the system or created by the users. Each case type is defined by it's own workflow. To track various steps  in the workflow, we used a Treeview structure in Powerbuilder.While I was doing some research on these flows, I had a need to document the flows in a flowchart. As always, I didn't want to just open Visio and draw a few. I wanted to script it, so it can be generated by text and better yet, automatically from the database with the information we have about the flows!

Since it's so easy to create graphs from the text files, we may even be able to build graphs dynamically, thus could represent state diagrams of running processes.

There are various resources available for DOT and dotty. Dotty is originally written in C. There is a Java API (Grappa) available that wraps around Dotty functions. Apart from Dot, there are also other languages available for representing graphs in text format.

References:

http://www.graphviz.org/Documentation.php

http://wapedia.mobi/en/DOT_language

http://code.google.com/apis/chart/image/docs/gallery/graphviz.html