1
.TH DOT 1 "02 December 1996" \*(eX
3
dot \- preprocessor for drawing directed graphs
5
\fBdot\fR [\fB\-G\fIname=value\fR]
6
[\fB\-N\fIname=value\fR]
10
[\fB\-o \fIoutfile\fR]
14
draws directed graphs. It works well on DAGs and other graphs
15
that can be drawn as hierarchies.
16
It reads attributed graph files and writes drawings.
17
By default, the output format
19
is the input file with layout coordinates appended.
20
To generate PostScript, use the \fB\-Tps\fP option.
21
Other choices are \fB-Tmif\fP (FrameMaker graphics),
22
\fB-Thpgl\fP (HP pen plotters), and \fB-Tpcl\fP (Laserjet printers),
23
\fB-Tgif\fP (pixel graphics),
25
and \fB-Tismap\fP (imagemap files for httpd servers
26
that mark out rectangles
27
for each node that has a non-null URL attribute.).
29
Here is a synopsis of the graph file language.
31
\fBdigraph \fIname\fP { \fIstatement-list\fP }\fR is the top level graph.
34
\fIname\fB=\fIval\fB;\fR
36
\fBnode [\fIname\fB=\fIval\fB];\fR
38
\fBedge [\fIname\fB=\fIval\fB];\fR
39
Set default graph, node, or edge attribute \fIname\fP to \fIval\fP.
40
Any subgraph, node, or edge appearing after this inherits the new
43
\fBn0 [\fIname0=val0,name1=val1,...\fB];\fR
44
Creates node \fBn0\fP (if it does not already exist)
45
and sets its attributes according to the optional list.
47
\fBn0 \-> n1 \-> \fI...\fB \-> nn [\fIname0=val0,name1=val1,...\fB];\fR
48
Creates edges between nodes \fBn0\fP, \fBn1\fP, ..., \fBnn\fP and sets
49
their attributes according to the optional list.
50
Creates nodes as necessary.
52
\fBsubgraph \fIname\fB { \fIstatement-list \fB}\fR
53
Creates a subgraph. Subgraphs may be used in place
54
of \fBn0\fP, ..., \fBnn\fP in the above statements to create edges.
55
\fBsubgraph \fIname\fR is optional;
56
if missing, the subgraph is assigned an internal name.
58
Comments may be /*C-like*/ or //C++-like.
60
Attribute names and values are ordinary (C-style) strings.
61
The following sections describe attributes that control graph layout.
62
.SH "GRAPH ATTRIBUTES"
64
\fBsize="\fIx,y\fP"\fR sets bounding box of drawing in inches.
66
\fBpage="\fIx,y\fP"\fR sets the PostScript pagination unit.
68
\fBratio=\fIf\fR sets the aspect ratio to \fIf\fP which may be
69
a floating point number, or one of the keywords \fBfill\fP,
70
\fBcompress\fP, or \fBauto\fP.
72
\fBmargin=\fIf\fR sets the page margin (included in the page size).
74
\fBnodesep=\fIf\fR sets the minimum separation between nodes.
76
\fBranksep=\fIf\fR sets the minimum separation between ranks.
78
\fBordering=out\fR constrains order of out-edges in a subgraph
79
according to their file sequence.
81
\fBrankdir=LR\fR requests a left-to-right drawing.
83
\fBpagedir=\fR[TBLR][TBLR] sets the major and minor order of pagination.
85
\fBrank=same\fR (or \fBmin\fP or \fBmax\fP) in a subgraph
86
constrains the rank assignment of its nodes. If a subgraph's
87
name has the prefix \fBcluster\fP, its nodes are drawn in
88
a distinct rectangle of the layout. Clusters may be nested.
90
\fBrotate=90\fR sets landscape mode.
91
(\fBorientation=land\fR is backward compatible but obsolete.)
93
\fBcenter=\fIn\fR a non-zero value centers the drawing on the page.
95
\fBnslimit=\fIf\fR or \fBmclimit=\fIf\fR adjusts the bound on the
96
number of network simplex or mincross iterations by the given ratio.
97
For example, \fBmclimit=2.0\fP runs twice as long.
99
\fBlayers="\fIid:id:id:id\fR" is a sequence of layer identifiers for
100
overlay diagrams. The PostScript array variable \fIlayercolorseq\fR
101
sets the assignment of colors to layers. The least index is 1 and
102
each element must be a 3-element array to be interpreted as a color coordinate.
104
\fBcolor=\fIcolorvalue\fR sets foreground color (\fBbgcolor\fP for background).
106
\fBURL=\fI"url"\fR the default url for image map files; in PostScript files,
107
the base URL for all relative URLs, as recognized by Acrobat Distiller
109
.SH "NODE ATTRIBUTES"
110
\fBheight=\fId\fR or \fBwidth=\fId\fR sets minimum height or width.
111
Adding \fBfixedsize=true\fP forces these to be the actual size
112
(text labels are ignored).
114
\fBshape=record polygon epsf \fIbuiltin_polygon\fR
116
\fIbuiltin_polygon\fR is one of: \fBplaintext ellipse circle egg
117
triangle box diamond trapezium parallelogram house hexagon octagon.\fR
118
(Polygons are defined or modified by the following node attributes:
119
\fBregular\fR, \fBperipheries\fR, \fBsides\fR, \fBorientation\fR,
120
\fBdistortion\fR and \fBskew\fR.) \fBepsf\fR uses the node's
121
\fBshapefile\fR attribute as the path name of an external
122
EPSF file to be automatically loaded for the node shape.
124
\fBlabel=\fItext\fR where \fItext\fP may include escaped newlines
125
\\\|n, \\\|l, or \\\|r for center, left, and right justified lines.
126
Record labels may contain recursive box lists delimited by { | }.
127
Port identifiers in labels are set off by angle brackets < >.
128
In the graph file, use colon (such as, \fBnode0:port28\fR).
130
\fBfontsize=\fIn\fR sets the label type size to \fIn\fP points.
132
\fBfontname=\fIname\fR sets the label font family name.
134
\fBcolor=\fIcolorvalue\fR sets the outline color, and the default fill color
135
if style=filled and \fBfillcolor\fR is not specified.
137
\fBfillcolor=\fIcolorvalue\fR sets the fill color
138
when style=filled. If not specified, the fillcolor when style=filled defaults
139
to be the same as the outline color.
141
\fBfontcolor=\fIcolorvalue\fR sets the label text color.
143
A \fIcolorvalue\fP may be "\fIh,s,v\fB"\fR (hue, saturation, brightness)
144
floating point numbers between 0 and 1, or an X11 color name such as
145
\fBwhite black red green blue yellow magenta cyan\fR or \fBburlywood\fR,
146
or a "\fI#rrggbb" (red, green, blue, 2 hex characters each) value.
148
\fBstyle=filled solid dashed dotted bold invis\fP or any Postscript code.
150
\fBlayer=\fIid\fR or \fIid:id\fR or "all" sets the node's active layers.
151
The empty string means no layers (invisible).
153
The following attributes apply only to polygon shape nodes:
155
\fBregular=\fIn\fR if \fIn\fR is non-zero then the polygon is made
156
regular, i.e. symmetric about the x and y axis, otherwise the
157
polygon takes on the aspect ratio of the label.
158
\fIbuiltin_polygons\fR that are not already regular are made regular
160
\fIbuiltin_polygons\fR that are already regular are not affected (i.e.
161
they cannot be made asymmetric).
163
\fBperipheries=\fIn\fR sets the number of periphery lines drawn around
164
the polygon. This value supercedes the number of periphery lines
165
of \fIbuiltin_polygons\fR.
167
\fBsides=\fIn\fR sets the number of sides to the polygon. \fIn\fR<3
168
results in an ellipse.
169
This attribute is ignored by \fIbuiltin_polygons\fR.
171
\fBorientation=\fIf\fR sets the orientation of the first apex of the
172
polygon counterclockwise from the vertical, in degrees.
173
\fIf\fR may be a floating point number.
174
The orientation of labels is not affected by this attribute.
175
This attribute is added to the initial orientation of \fIbuiltin_polygons.\fR
177
\fBdistortion=\fIf\fR sets the amount of broadening of the top and
178
narrowing of the bottom of the polygon (relative to its orientation).
179
Floating point values between -1 and +1 are suggested.
180
This attribute is ignored by \fIbuiltin_polygons\fR.
182
\fBskew=\fIf\fR sets the amount of right-displacement of the top and
183
left-displacement of the bottom of the polygon (relative to its
185
Floating point values between -1 and +1 are suggested.
186
This attribute is ignored by \fIbuiltin_polygons\fR.
188
\fBURL=\fI"url"\fR sets the url for the node in image map and PostScript
189
files. The string '\\N' value will be replaced by the node name. In
190
PostScript files, URL information is embedded in such a way that Acrobat
191
Distiller creates PDF files with active hyperlinks.
193
.SH "EDGE ATTRIBUTES"
194
\fBminlen=\fIn\fR where \fIn\fP is an integer factor that applies
195
to the edge length (ranks for normal edges, or minimum node separation
198
\fBweight=\fIn\fR where \fIn\fP is the integer cost of the edge.
199
Values greater than 1 tend to shorten the edge. Weight 0 flat
200
edges are ignored for ordering nodes.
202
\fBlabel=\fItext\fR where \fItext\fR may include escaped newlines
203
\\\|n, \\\|l, or \\\|r for centered, left, or right justified lines.
205
\fBfontsize=\fIn\fR sets the label type size to \fIn\fP points.
207
\fBfontname=\fIname\fR sets the label font family name.
209
\fBfontcolor=\fIcolorvalue\fR sets the label text color.
211
\fBstyle=solid dashed dotted bold invis\fP
213
\fBcolor=\fIcolorvalue\fR sets the line color for edges.
215
\fBdir=forward back both none\fP controls arrow direction.
217
\fBtailclip,headclip=false\fP disables endpoint shape clipping.
219
\fBarrowhead,arrowtail=none,normal,inv,dot,odot,invdot,invodot\fP.
221
\fBarrowsize\fP (norm_length=10,norm_width=5,
222
inv_length=6,inv_width=7,dot_radius=2)
224
\fBheadlabel,taillabel=string\fP for port labels.
225
\fBlabelfontcolor\fP,\fBlabelfontname\fP,\fBlabelfontsize\fP
226
for head and tail labels.
228
\fBlabeldistance\fP and \fPport_label_distance\fP set distance; also
229
\fBlabelangle\fP (in degrees CCW)
231
\fBdecorate\P draws line from edge to label.
233
\fBsamehead,sametail\fP aim edges having the same value to the
234
same port, using the average landing point.
236
\fBconstraint=false\fP causes an edge to be ignored for rank assignment.
238
\fBlayer=\fIid\fR or \fIid:id\fR or "all" sets the edgess active layers.
239
The empty string means no layers (invisible).
241
\fB\-G\fP sets a default graph attribute.
242
\fB\-N\fP and \fB\-E\fP set default attributes for nodes and edges.
243
Some examples: \fB\-Gsize="7,8"\fP or \fB\-Nshape=box\fP or \fB\-Efontsize=8\fP.
245
\fB\-l\fIfile\fR loads custom PostScript library files.
246
Usually these define custom shapes or styles.
247
If \fB-l\fP is given by itself, the standard library is omitted.
249
\fB\-T\fIlang\fR sets the output language as described above.
260
c [label="hello\\\|nworld",color=blue,fontsize=24,
262
fontname="Palatino-Italic",fontcolor=red,style=filled];
264
a \-> z [label="hi", weight=100];
266
x \-> z [label="multi-line\\\|nlabel"];
268
edge [style=dashed,color=red];
277
Edge splines can overlap unintentionally.
279
Flat edge labels are slightly broken.
280
Intercluster edge labels are totally broken.
294
E. R. Gansner, S. C. North, K. P. Vo, "DAG \(em A Program to Draw Directed Graphs", Software \(em Practice and Experience 17(1), 1988, pp. 1047-1062.
296
E. R. Gansner, E. Koutsofios, S. C. North, K. P. Vo, "A Technique for Drawing Directed Graphs," IEEE Trans. on Soft. Eng. 19(3), 1993, pp. 214-230.
298
S. North and E. Koutsofios, "Applications of graph visualization",
299
Graphics Interface 94, pp. 234-245.
301
E. Koutsofios and S. C. North, "Drawing Graphs with dot,"
302
Available on research.att.com in dist/drawdag/dotguide.ps.Z.
304
The GIF driver is a publically available library from the Quest Center
305
at Cold Spring Harbor Labs (courtesy Tom Boutell, boutell@netcom.com).
306
The Truetype font renderer for the GIF driver was written by
307
the Freetype Project (David Turner, Robert Wilhelm, and Werner Lemberg)
308
(who can be contacted at freetype-devel@lists.lrz-muenchen.de).