Plot:Design:Dot

From Adonthell
Jump to: navigation, search

This section introduces a program that greatly simplifies the creation of the dependency graph. Read on if you ever plan to work on that.

Introduction

Creating the dependency graph is possibly the biggest problem when documenting the plot. As it will undergo frequent changes and updates, an ordinary graphics package such as The Gimp or Photoshop isn’t suitable for drawing the graph. Vector drawing tools are much more fitting, but they still force the user to manually arrange and connect nodes, making dependency graph maintenence a time consuming business. This is where dot comes in, a lightweight command line utility that draws directed graphs from a textual description. It is part of AT&T’s graphviz package and freely available for various platforms.

Examples

To learn about all of dot’s features you should refer to its user manual. But if all you want to do is creating plot dependency graphs, then the examples below should be enough to get you going. They all show a graph on the left and the code to create it on the right.

Plot design mini.png
  digraph minimalistic 
  { 
    n1 [label = "Node 1"]; 
    n2 [label = "Node 2"]; 
    
    n1 -> n2 
  };

The example above demonstrates the basic layout of a .dot file. They always start with the digraph keyword, followed by a custom name for the graph. Two nodes are then defined and labelled accordingly. The last line finally creates an edge between those nodes.

Plot design nodes.png
  digraph nodes 
  { 
    rect [shape = polygon, sides = 4, 
    label = "Rectangle"]; 

    none [shape = plaintext, 
    label = "Plain Text"]; 

    rect -> none [label = "Edge\nLabel"]; 
  }; 

This example shows how to create nodes with different styles. Edges can have labels too, and ‘\n’ can be used to add custom linebreaks to any label.

Plot design example3.png
digraph complete 
{
  // keyoints
  start  [shape=polygon, sides=4, 
          label="Start"]; 
  wizard [shape=polygon, sides=4, 
          label="Encounter\nwith\nWizard"]; 
  end    [shape=polygon, sides=4, 
          label="End"]; 

  start->wizard->end 

  // activities
  intro [label="1 Intro"]; 
  git   [label="2 Get into\nTower"]; 
  dw    [label="3 Defeat\nWizard"]; 
  tuww [label="4 Team\nup with\nWizard"]; 
  fp    [label="5 Free\nPrincess"]; 
  sp    [label="6 Sacrifice\nPrincess"]; 

  intro->git->dw->fp 
  git->tuww->sp 

  // align keypoints and activities
  { rank=same; start; intro; } 
  { rank=same; wizard; dw; tuww; } 
  { rank=same; end; fp; sp; } 
}; 

The last example finally shows how to add keypoints to the graph, and how to align them with corresponding nodes. That’s what the last few lines are for. Once you have created a .dot file, you can turn it into a PNG image of the graph by running dot -Tpng -o image.png file.dot from a shell or DOS box.

dot and LaTeX

As seen above, dot can produce pixel graphics of a graph. However, if we want to compile the plot documentation into a nice PDF file for example, vector graphics would improve the document’s appearance considerably. Unfortunately, pdftex cannot use any of the vector formats produced by dot directly. But, as the Plot Design Guidelines show, there is a way to convert its postscript output into something usable. The following guide assumes that you are using graphviz 1.8.5 or later.

  • Step 1 Create the postscript version of the graph. This is done by invoking dot with the following parameters:
    dot -Tps2 -o image.ps file.dot
  • Step 2 Turn the .ps file into valid EPS format. This especially involves fixing the Bounding Box, i.e. the extensions of the graph. This can be achieved with a tool like ps2eps:
    ps2eps -f image.ps
  • Step 3 Turn the .eps file into a format understandable by pdftex, i.e. PDF:
    epstopdf image.eps

This will finally produce an image.pdf file, which can be used by \includegraphics and similar LaTeX commands. To automate the whole process, the following Makefile might prove to be useful:

 IMAGES = <list of .pdf files> 
 
 all: ${IMAGES} 
 
 %.pdf: %.eps 
     epstopdf $< 
 
 %.eps: %.ps 
     ps2eps -f $< 
 
 %.ps: %.dot 
     dot -Tps2 -o $*.ps $< 

Note that this description is not meant to be exhaustive. It is little more than a reminder for the author himself, but it should get you started. Much more information on this topic is available from various sources on the internet.

Personal tools
Namespaces

Variants
Actions
Navigation
Exits
Tools