Mercurial > hg > camir-ismir2012

annotate toolboxes/graph_visualisation/share/graphviz/doc/html/FAQ.html @ 0:cc4b1211e677 tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial commit to HG from Changeset: 646 (e263d8a21543) added further path and more save "camirversion.m"
author Daniel Wolff
date Fri, 19 Aug 2016 13:07:06 +0200
parents
children
rev   line source
Daniel@0 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
Daniel@0 2 "http://www.w3.org/TR/html4/loose.dtd">
Daniel@0 3 <HTML><HEAD><TITLE>Graphviz FAQ 2008-06-06</TITLE>
Daniel@0 4 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=utf-8">
Daniel@0 5 </HEAD><BODY>
Daniel@0 6 <H1>Graphviz FAQ 2008-06-06</H1>
Daniel@0 7
Daniel@0 8 <A HREF="mailto:gviz-bugs@research.att.com">The Graphviz Project</A>
Daniel@0 9 <p>
Daniel@0 10 <b>Note</b>:
Daniel@0 11 This is not a tutorial; to understand the following, you should
Daniel@0 12 know how to use the basic features of the tools and
Daniel@0 13 languages involved. Please see the
Daniel@0 14 <A HREF="http://www.graphviz.org/Documentation.php">
Daniel@0 15 user guides and documentation</A> for further information or the
Daniel@0 16 <A HREF="http://www.graphviz.org/Resources.php">resources page</A>
Daniel@0 17 for a partial list of compatible tools and packages.
Daniel@0 18
Daniel@0 19 <h2>General</h2>
Daniel@0 20
Daniel@0 21 <A name=Q1 HREF=#Q1>
Daniel@0 22 <B>Q1</A>. Where can I see a list of all the attributes that control dot or neato?</B>
Daniel@0 23
Daniel@0 24 </A>
Daniel@0 25 <P>
Daniel@0 26 See <A HREF="info/attrs.html">
Daniel@0 27 Graph Attributes</A>. There is also information on
Daniel@0 28 <A HREF="info/command.html">
Daniel@0 29 command-line usage</A> and
Daniel@0 30 <A HREF="info/output.html">
Daniel@0 31 output formats</A>.
Daniel@0 32 <p>
Daniel@0 33 <a name="mailinglist"></a>
Daniel@0 34 <A name=Q2 HREF=#Q2>
Daniel@0 35 <B>Q2</A>. Where can I discuss Graphviz?</B>
Daniel@0 36
Daniel@0 37 <p>
Daniel@0 38 We run a mailing list.
Daniel@0 39 <p>
Daniel@0 40 To subscribe or unsubscribe, visit the
Daniel@0 41 <A HREF="https://mailman.research.att.com/mailman/listinfo/graphviz-interest">graphviz-interest</A> <em>mailman</em> control page. See also the general
Daniel@0 42 <A HREF="http://www.list.org/mailman-member/index.html">
Daniel@0 43 instructions</A> for mailman.
Daniel@0 44 <p>
Daniel@0 45 You can also see the
Daniel@0 46 <A HREF="https://mailman.research.att.com/pipermail/graphviz-interest/">
Daniel@0 47 archive</A>.
Daniel@0 48 <p>
Daniel@0 49 You may wish to use a Yahoo or Hotmail account if you're concerned
Daniel@0 50 about spam. We also run anti-spam filters, and rewrite <tt>@</tt>
Daniel@0 51 as <tt>at</tt> to keep verbatim addresses out of the archive.
Daniel@0 52 <p>
Daniel@0 53 Please, please, please, do not torment the mailing list with beginner's
Daniel@0 54 questions. First, check this FAQ and the
Daniel@0 55 <A HREF="https://mailman.research.att.com/pipermail/graphviz-interest/">
Daniel@0 56 message archive</A> carefully.
Daniel@0 57 If you are desperate, or better yet, if you have constructive advice,
Daniel@0 58 please send a message to the <A HREF="https://mailman.research.att.com/mailman/listinfo/graphviz-devel">graphviz-devel mailing list</A>.
Daniel@0 59 <p>
Daniel@0 60 Also, if a program crashes or you get an abort or something strange occurs
Daniel@0 61 and you are fairly comfortable using the tools:
Daniel@0 62 <UL>
Daniel@0 63 <LI>
Daniel@0 64 Check the
Daniel@0 65 <A HREF="http://www.research.att.com/~erg/graphviz/bugs/openbugs.html"> open
Daniel@0 66 bug list</A> to see if a similar bug has already been reported. You might
Daniel@0 67 also consider checking the
Daniel@0 68 <A HREF="http://www.research.att.com/~erg/graphviz/bugs/buglist.html"> full
Daniel@0 69 bug list</A>, since your bug may have been reported and fixed in the working
Daniel@0 70 version.
Daniel@0 71 <LI>
Daniel@0 72 Submit a <A HREF="http://www.research.att.com/~erg/graphviz/bugform.html">bug
Daniel@0 73 report</A>. If you prefer, you can download a
Daniel@0 74 <A HREF="http://www.research.att.com/~erg/graphviz/bugform.txt">report in
Daniel@0 75 text form</A>, fill in the fields, and email it to
Daniel@0 76 <a href="mailto:gviz-bugs@research.att.com">gviz-bugs@research.att.com</a>.
Daniel@0 77 </UL>
Daniel@0 78 <p>
Daniel@0 79 <A name=Q3 HREF=#Q3>
Daniel@0 80 <B>Q3</A>. I'm trying to make a layout larger. How?</B>
Daniel@0 81
Daniel@0 82 <p>
Daniel@0 83 There are various ways to increase the size of a layout. In doing this,
Daniel@0 84 one has to decide if the sizes of the nodes and text should be
Daniel@0 85 increased as well.
Daniel@0 86 <p>
Daniel@0 87 One approach is to adjust individual
Daniel@0 88 parameters such as <tt>fontsize, nodesep</tt> and <tt>ranksep</tt>.
Daniel@0 89 For example,
Daniel@0 90 <pre>
Daniel@0 91 digraph G {
Daniel@0 92 graph [fontsize=24];
Daniel@0 93 edge [fontsize=24];
Daniel@0 94 node [fontsize=24];
Daniel@0 95 ranksep = 1.5;
Daniel@0 96 nodesep = .25;
Daniel@0 97 edge [style="setlinewidth(3)"];
Daniel@0 98 a -&gt; b -&gt; c;
Daniel@0 99 }
Daniel@0 100 </pre>
Daniel@0 101 If you do this, make sure you are not fighting a conflicting graph
Daniel@0 102 size setting, like <tt>size="6,6"</tt>, which will then scale
Daniel@0 103 everything back down.
Daniel@0 104 <p>
Daniel@0 105 If you are using fdp or neato, increasing the edge len will tend to
Daniel@0 106 expand the layout.
Daniel@0 107 <pre>
Daniel@0 108 graph G {
Daniel@0 109 edge [len=3]
Daniel@0 110 a -- { b c d }
Daniel@0 111 }
Daniel@0 112 </pre>
Daniel@0 113 For twopi and circo, there are other parameters such as
Daniel@0 114 <tt>ranksep</tt> which can be used. See the
Daniel@0 115 <A HREF="info/attrs.html">
Daniel@0 116 graph attributes</A>.
Daniel@0 117 <p>
Daniel@0 118 You can also use the <tt>ratio</tt> attribute. If you set the <tt>size</tt>
Daniel@0 119 attribute to the desired drawing size, and then set <tt>ratio=fill</tt>, node
Daniel@0 120 positions are scaled separately in x and y until the drawing fills the
Daniel@0 121 specified <tt>size</tt>. Note that node sizes stay the same. If, instead,
Daniel@0 122 you set <tt>ratio=expand</tt>, the layout is uniformly scaled up in x and y
Daniel@0 123 until at least one dimension fits <tt>size</tt>.
Daniel@0 124 <p>
Daniel@0 125 If you specify the <tt>size</tt> attribute but end it with an exclamation
Daniel@0 126 mark (!), the final drawing will be scaled up uniformly in x and y
Daniel@0 127 until at least one dimension fits <tt>size</tt>. Note that everything is
Daniel@0 128 scaled up, including text and node sizes.
Daniel@0 129 <p>
Daniel@0 130 If you're using Postscript, you can just scale up the output by
Daniel@0 131 manually adding a command such as <tt>2 2 scale</tt> where the
Daniel@0 132 Postscript environment is set up. Make sure to adjust the
Daniel@0 133 <tt>BoundingBox</tt> too if your tools look at this header.
Daniel@0 134 <p>
Daniel@0 135 <A name=Q4 HREF=#Q4>
Daniel@0 136 <B>Q4</A>. How can I join or merge certain edge routes in dot?</B>
Daniel@0 137
Daniel@0 138 <p>
Daniel@0 139 You can try running <tt>dot -Gconcentrate=true</tt> or you can
Daniel@0 140 introduce your own virtual nodes drawn as tiny circles where
Daniel@0 141 you want to split or join edges:
Daniel@0 142
Daniel@0 143 <pre>
Daniel@0 144 digraph G {
Daniel@0 145 yourvirtualnode [shape=circle,width=.01,height=.01,label=""];
Daniel@0 146 a -&gt; yourvirtualnode [arrowhead=none]
Daniel@0 147 yourvirtualnode -&gt; {b;c}
Daniel@0 148 }
Daniel@0 149 </pre>
Daniel@0 150
Daniel@0 151 <P>
Daniel@0 152 <A name=Q4a>
Daniel@0 153 <B>Q. How can I generate graph layouts in PDF?</B>
Daniel@0 154 </A>
Daniel@0 155 <P>
Daniel@0 156 Recent versions of graphviz with the CairoPango based drivers
Daniel@0 157 can generate PDF directly with the <tt>-Tpdf</tt> command line option.
Daniel@0 158 This this first.
Daniel@0 159 <P>
Daniel@0 160 Otherwise, create Postscript output, then use an external converter from
Daniel@0 161 Postscript to PDF.
Daniel@0 162 For example,<BR>
Daniel@0 163 <tt>dot -Tps | epsf2pdf -o file.pdf</tt><br>
Daniel@0 164 Note that URL tags are respected, to allow clickable PDF objects.
Daniel@0 165 <P>
Daniel@0 166 If your intention is to use the figure as PDF in some document preparation
Daniel@0 167 system, such as pdflatex, it is very important to use -Tps2 rather than
Daniel@0 168 -Tps. In general, if you really want PDF output, that is, you would like
Daniel@0 169 to have a -Tpdf flag, use -Tps2 before converting to PDF.
Daniel@0 170 <P>
Daniel@0 171 In the diagram below, the shaded nodes will contain bad output.<BR>
Daniel@0 172 <IMG src="pspdf.png">
Daniel@0 173 <P>
Daniel@0 174 <A name=Q4b>
Daniel@0 175 <B>Q. How can I make duplicate nodes?</B>
Daniel@0 176 </A>
Daniel@0 177 <P>
Daniel@0 178 Make unique nodes with duplicate labels.
Daniel@0 179 <pre>
Daniel@0 180 digraph G {
Daniel@0 181 node001 [label = "A"];
Daniel@0 182 node002 [label = "A"];
Daniel@0 183 node001 -&gt; node002;
Daniel@0 184 }
Daniel@0 185 </pre>
Daniel@0 186 <P>
Daniel@0 187 <A name=Q4c>
Daniel@0 188 <B>Q. How can I set a graph or cluster label without its propagating to all sub-clusters?</B>
Daniel@0 189 </A>
Daniel@0 190 <P>
Daniel@0 191 Set the label at the end of the graph (before the closing brace), after all
Daniel@0 192 its contents have been defined. (We admit it seems desirable to define some
Daniel@0 193 special syntax for non-inherited attribute settings.)
Daniel@0 194 <p>
Daniel@0 195 <A name=Q5 HREF=#Q5>
Daniel@0 196 <B>Q5</A>. How can I draw multiple parallel edges in neato?</B>
Daniel@0 197
Daniel@0 198 <p>
Daniel@0 199 This is possible when the <tt>splines</tt> attribute is false, which
Daniel@0 200 is the default. When <tt>splines=true</tt>, we have no good answer but
Daniel@0 201 we are working on it. One trick which is sometimes sufficient is to
Daniel@0 202 specify multiple colors for the edge. This will a produce set of tightly
Daniel@0 203 parallel splines, each in its specified color. Read about the
Daniel@0 204 <A HREF="info/attrs.html#d:color">color
Daniel@0 205 attribute</A> for more information.
Daniel@0 206
Daniel@0 207 <h2>Clusters</h2>
Daniel@0 208
Daniel@0 209 <A name=Q5a>
Daniel@0 210 <B>Q. How can I create edges between cluster boxes?</B>
Daniel@0 211 </A>
Daniel@0 212 <p>
Daniel@0 213 This only works in Graphviz version 1.7 and higher.
Daniel@0 214 To make edges between clusters, first set the
Daniel@0 215 graph attribute <tt>compound=true</tt>.
Daniel@0 216 Then, you can specify a cluster by name as
Daniel@0 217 a <i>logical head or tail</i> to an edge. This will
Daniel@0 218 cause the edge joining the two nodes to be
Daniel@0 219 clipped to the exterior of the box around the
Daniel@0 220 given cluster.
Daniel@0 221 <p>
Daniel@0 222 For example,
Daniel@0 223
Daniel@0 224 <pre>
Daniel@0 225 digraph G {
Daniel@0 226 compound=true;
Daniel@0 227 nodesep=1.0;
Daniel@0 228 subgraph cluster_A {
Daniel@0 229 a -&gt; b;
Daniel@0 230 a -&gt; c;
Daniel@0 231 }
Daniel@0 232 subgraph cluster_B {
Daniel@0 233 d -&gt; e;
Daniel@0 234 f -&gt; e;
Daniel@0 235 }
Daniel@0 236 a -&gt; e [ ltail=cluster_A,
Daniel@0 237 lhead=cluster_B ];
Daniel@0 238 }
Daniel@0 239 </pre>
Daniel@0 240
Daniel@0 241 has an edge going from <tt>cluster_A</tt> to
Daniel@0 242 <tt>cluster_B</tt>. If, instead, you say
Daniel@0 243
Daniel@0 244 <pre>
Daniel@0 245 a -&gt; e [ltail=cluster_A];
Daniel@0 246 </pre>
Daniel@0 247
Daniel@0 248 this gives you an edge from <tt>cluster_A</tt> to node
Daniel@0 249 <tt>e</tt>. Or you could just specify
Daniel@0 250 an <tt>lhead</tt> attribute.
Daniel@0 251
Daniel@0 252 The program warns if a cluster specified as a
Daniel@0 253 logical node is not defined.
Daniel@0 254 Also, if a cluster is specified as a logical
Daniel@0 255 head for an edge, the real
Daniel@0 256 head must be contained in the cluster, and
Daniel@0 257 the real tail must not be.
Daniel@0 258 A similar check is done for logical tails. In
Daniel@0 259 these cases, the edge
Daniel@0 260 is drawn between the real nodes as usual.
Daniel@0 261 <p>
Daniel@0 262 <A name=Q6 HREF=#Q6>
Daniel@0 263 <B>Q6</A>. Clusters are hard to see.</B>
Daniel@0 264
Daniel@0 265 <P>
Daniel@0 266 Set <tt>bgcolor=grey</tt>
Daniel@0 267 (or some other color)
Daniel@0 268 in the cluster.
Daniel@0 269 <P>
Daniel@0 270 <A name=Q7 HREF=#Q7>
Daniel@0 271 <B>Q7</A>. How can I symmetrize (balance) tree layouts?</B>
Daniel@0 272
Daniel@0 273 <P>
Daniel@0 274 When a tree node has an even number of children, it isn't necessarily
Daniel@0 275 centered above the two middle ones. If you know the order of the children,
Daniel@0 276 a simple hack is to introduce new, invisible middle nodes to re-balance
Daniel@0 277 the layout. The connecting edges should also be invisible. For example:
Daniel@0 278 <pre>
Daniel@0 279 digraph G {
Daniel@0 280 a -&gt; b0;
Daniel@0 281 xb [label="",width=.1,style=invis]
Daniel@0 282 a -&gt; xb [style=invis];
Daniel@0 283 a -&gt; b1;
Daniel@0 284 {rank=same b0 -&gt; xb -&gt; b1 [style=invis]}
Daniel@0 285 b0 -&gt; c0;
Daniel@0 286 xc [label="",width=.1,style=invis]
Daniel@0 287 b0 -&gt; xc [style=invis];
Daniel@0 288 b0 -&gt; c1;
Daniel@0 289 {rank=same c0 -&gt; xc -&gt; c1 [style=invis]}
Daniel@0 290 }
Daniel@0 291 </pre>
Daniel@0 292 This trick really ought to be build into our solver (and made
Daniel@0 293 independent of the order of the children, and available for
Daniel@0 294 layouts other than trees, too).
Daniel@0 295
Daniel@0 296 <H2>Output features</H2>
Daniel@0 297
Daniel@0 298 <A name=Q8 HREF=#Q8>
Daniel@0 299 <B>Q8</A>. How can I get high quality (antialiased) output?</B>
Daniel@0 300
Daniel@0 301 <P>
Daniel@0 302 The easiest thing may be to make the layout in Postscript (option <tt>-Tps</tt>),
Daniel@0 303 then run through <A HREF="http://www.cs.wisc.edu/~ghost/">Ghostview</A> with
Daniel@0 304 antialiasing enabled. The important command line options are
Daniel@0 305 <tt>-dTextAlphaBits=4 -dGraphicsAlphaBits=4</tt>
Daniel@0 306 (4 is the highest level of antialiasing allowed - see the
Daniel@0 307 <A HREF="http://www.cs.wisc.edu/~ghost/doc/GPL/8.15/Use.htm">Ghostview documentation</A>).
Daniel@0 308 The full command line to render a raster could be something like:
Daniel@0 309 <pre>
Daniel@0 310 gs -q -dNOPAUSE -dBATCH -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -sDEVICE=png16m -sOutputFile=file.png file.ps
Daniel@0 311 </pre>
Daniel@0 312 <P>
Daniel@0 313 On Mac OS X, the <A HREF="http://www.pixelglow.com/graphviz/">pixelglow</A> port
Daniel@0 314 uses Apple's Quartz renderer, which enables antialiasing. It also provides a beautiful document container for its user interface. (One downside is
Daniel@0 315 that you can't run Pixelglow Graphviz as a web server or other background
Daniel@0 316 process if your Mac has 3D graphics, because Quartz wants to get this resource
Daniel@0 317 to accelerate rendering. Another problem is that as of this writing,
Daniel@0 318 Pixelglow Graphviz hasn't been updated in a long time, maybe mid 2004.)
Daniel@0 319 <P>
Daniel@0 320 On the Linux bleeding edge, Graphviz has an optional plugin to use
Daniel@0 321 the <A HREF="http://www.cairographics.org">cairo</A> back end,
Daniel@0 322 which has antialiased, path-based graphics. If you want this,
Daniel@0 323 you must install cairo, which is not part of Graphviz. Cairo is
Daniel@0 324 available in recent versions of Fedora linux, or it can be built
Daniel@0 325 from source.
Daniel@0 326 <P>
Daniel@0 327 <A name=Q9 HREF=#Q9>
Daniel@0 328 <B>Q9</A>. I can only get 11x17 output.</B>
Daniel@0 329
Daniel@0 330 <P>
Daniel@0 331 It's not us! It's probably your printer setup. If you don't
Daniel@0 332 believe this, run <tt>dot -Tps</tt> and look at the
Daniel@0 333 <tt>BoundingBox</tt> header. The coords are in 1/72ths of an inch.
Daniel@0 334
Daniel@0 335 <P>
Daniel@0 336 <A name=Q10 HREF=#Q10>
Daniel@0 337 <B>Q10</A>. How do I create special symbols and accents in labels?</B>
Daniel@0 338
Daniel@0 339 <P>
Daniel@0 340 The following solution only works with the
Daniel@0 341 raster drivers that load Truetype or Type1
Daniel@0 342 fonts! (That means, <tt>-Tgif, -Tpng, -Tjpeg</tt>, and possibly
Daniel@0 343 <tt>-Tbmp</tt> or <tt>-Txbm</tt> if enabled).
Daniel@0 344
Daniel@0 345 Use UTF8 coding, <i>e.g.</i> &amp;#165; for the Yen currency symbol &#165.
Daniel@0 346 Example:
Daniel@0 347
Daniel@0 348 <pre>
Daniel@0 349 graph G {
Daniel@0 350 yen [label="&amp#165;"]
Daniel@0 351 }
Daniel@0 352 </pre>
Daniel@0 353 <P>
Daniel@0 354 You can look up other examples in this handy
Daniel@0 355 <A HREF="http://www.graphviz.org/doc/char.html">
Daniel@0 356 character set reference</A>.
Daniel@0 357 <P>
Daniel@0 358 <A name=Q10b>
Daniel@0 359 <B>Q. More generally, how do I use non-ASCII character sets?</B>
Daniel@0 360 </A>
Daniel@0 361 <P>
Daniel@0 362 The following applies to Graphviz 2.8 and later. (In older versions
Daniel@0 363 of Graphviz, you can sometimes get away with simply putting
Daniel@0 364 Latin-1 or other UTF-8 characters in the input stream, but the
Daniel@0 365 results are not always correct.)
Daniel@0 366 <P>
Daniel@0 367 <B>Input:</B> the general idea is to find the
Daniel@0 368 <A HREF="http://en.wikipedia.org/wiki/Unicode">Unicode</A>
Daniel@0 369 value for the glyph you want, and enter it within a text
Daniel@0 370 string "...." or HTML-like label <...>.
Daniel@0 371 <P>
Daniel@0 372 For example, the mathematical <it>forall</it> sign (&#8704;) has the value 0x2200.
Daniel@0 373 There are several ways this can be inserted into a file.
Daniel@0 374 One is to write out the ASCII representation: "&amp;#&lt;nnn&gt;;" where &lt;nnn&gt;
Daniel@0 375 is the decimal representation of the value. The decimal value of 0x2200 is 8704,
Daniel@0 376 so the character can be specified as "&amp;#8704;" . Alternatively, Graphviz
Daniel@0 377 accepts UTF-8 encoded input. In the case of forall, its UTF-8 representation
Daniel@0 378 is 3 bytes whose decimal values are 226 136 128. For convenience, you
Daniel@0 379 would probably enter this using your favorite editor, tuned to your character set
Daniel@0 380 of choice. You can then use the <A HREF="http://www.gnu.org/software/libiconv/#TOCdownloading">
Daniel@0 381 iconv</A> program to map the graph from your character set to UTF-8 or Latin-1.
Daniel@0 382 <P>
Daniel@0 383 We also accept the HTML symbolic names for Latin-1 characters as suggested
Daniel@0 384 <A HREF="#Q10">above</A>.
Daniel@0 385 (Go to http://www.research.att.com/~john/docs/html/index.htm and click
Daniel@0 386 on Special symbols and Entities) For example, the cent sign (unicode
Daniel@0 387 and Latin-1 value decimal 162 can be inserted as
Daniel@0 388 <pre>
Daniel@0 389 &amp;cent;
Daniel@0 390 </pre>
Daniel@0 391 <P>
Daniel@0 392 Note that <b>the graph file must always be a plain text document</b>
Daniel@0 393 not a Word or other rich format file. Any characters not enclosed in "..."
Daniel@0 394 or <...> must be ordinary ASCII characters. In particular, all of the DOT
Daniel@0 395 keywords such as <tt>digraph</tt> or <tt>subgraph</tt> must be ASCII.
Daniel@0 396 <P>
Daniel@0 397 Because we cannot always guess the encoding, you should set the graph
Daniel@0 398 attribute <tt>charset</tt> to
Daniel@0 399 <A HREF="http://en.wikipedia.org/wiki/UTF-8">UTF-8</A>,
Daniel@0 400 <A HREF="http://en.wikipedia.org/wiki/Latin-1">Latin1</A>
Daniel@0 401 (alias ISO-8859-1 or ISO-IR-100)
Daniel@0 402 or
Daniel@0 403 <A HREF="http://en.wikipedia.org/wiki/Big-5">Big-5</A> for
Daniel@0 404 Traditional Chinese. This can be done in the graph file or on the command line.
Daniel@0 405 For example <tt>charset=Latin1</tt>.
Daniel@0 406 <P>
Daniel@0 407 <B>Output:</B> It is essential that a font which has the glyphs for your
Daniel@0 408 specified characters is available at final rendering time.
Daniel@0 409 The choice of this font depends on the target code generator.
Daniel@0 410 For the gd-based raster generators (PNG, GIF, etc.) you need a
Daniel@0 411 TrueType or Type-1 font file on the machine running the Graphviz program.
Daniel@0 412 If Graphviz is built with the <tt>fontconfig</tt>
Daniel@0 413 library, it will be used to find the specified font. Otherwise, Graphviz will
Daniel@0 414 look in various default directories for the font. The directories to be
Daniel@0 415 searched include those specified by the <tt>fontpath</tt> attribute,
Daniel@0 416 related environment or shell variables
Daniel@0 417 (see the <a href=http://www.graphviz.org/doc/info/attrs.html#d:fontpath>fontpath</A> entry),
Daniel@0 418 and known system font directories.
Daniel@0 419 The table
Daniel@0 420 <A HREF="http://www.graphviz.org/doc/char.html">
Daniel@0 421 http://www.graphviz.org/doc/char.html</A>
Daniel@0 422 points out that these glyphs are from the <tt>times.ttf</tt> font.
Daniel@0 423 With fontconfig, it's hard to specify this font. <tt>Times</tt> usually gets
Daniel@0 424 resolved to Adobe Type1 times, which doesn't have all the glyphs seen on that page.)
Daniel@0 425 <!--- can someone explain whether Cairo differs from libgd here? --->
Daniel@0 426 <P>
Daniel@0 427 For Postscript, the input must be either the ASCII subset of UTF-8
Daniel@0 428 or Latin-1. (We have looked for more general solutions, but it
Daniel@0 429 appears that UTF-8 and Unicode are handled differently for every
Daniel@0 430 kind of font type in Postscript, and we don't have time to hack
Daniel@0 431 this case-by-case. If someone wants to volunteer to work on this, let us know.)
Daniel@0 432 <P>
Daniel@0 433 For SVG output, we just pass the raw UTF-8 (or other encoding)
Daniel@0 434 straight through to the generated code.
Daniel@0 435 <P>
Daniel@0 436 Non-ASCII characters probably won't ever work in Grappa
Daniel@0 437 or dotty, which have their own back end rendering.
Daniel@0 438 (Though, Java supports UTF-8, so there's a chance
Daniel@0 439 Grappa also handles raw UTF-8 strings.)
Daniel@0 440 <P>
Daniel@0 441 As you can see, this is a sad state of affairs.
Daniel@0 442 Our plan is to eventually migrate Graphviz to the
Daniel@0 443 <A HREF="http://www.pango.org/">pango</A> text formatting
Daniel@0 444 library, to ameliorate the worst of these complications.
Daniel@0 445 <P>
Daniel@0 446 <A name = Q11>
Daniel@0 447 <B>Q. How do I get font and color changes in record labels or other labels?</B>
Daniel@0 448 </A>
Daniel@0 449 <P>
Daniel@0 450 This is not possible in record shapes. However, you can do this using
Daniel@0 451 <A HREF="info/shapes.html#html">
Daniel@0 452 HTML-like labels</A>. The granularity of changes is still at the cell level,
Daniel@0 453 but by playing with cell spacing and padding, you can get pretty much
Daniel@0 454 the effect you want. The intention is to support arbitrary font changes
Daniel@0 455 within running text in the not-too-distant future.
Daniel@0 456
Daniel@0 457 <P>
Daniel@0 458 <A name=Q12 HREF=#Q12>
Daniel@0 459 <B>Q12</A>. In plain format, splines do not touch the nodes (arrowheads are missing).</B>
Daniel@0 460
Daniel@0 461 <P>
Daniel@0 462 Edges are specified as the main spline and, if necessary, arrowheads
Daniel@0 463 which actually abut the node. If the arrowheads are not given, drawing
Daniel@0 464 the edge spline will leave a gap between the edge and the node.
Daniel@0 465 This is a bug which has now solidified into a feature.
Daniel@0 466 A workaround is to set
Daniel@0 467
Daniel@0 468 <pre>
Daniel@0 469 edge [dir=none]
Daniel@0 470 </pre>
Daniel@0 471 Since the edges have no arrowheads, the spline specification will go
Daniel@0 472 all the way to both nodes.
Daniel@0 473 <P>
Daniel@0 474 <A name=Q13 HREF=#Q13>
Daniel@0 475 <B>Q13</A>. Record nodes are drawn differently in dot and neato when rankdir=LR.</B>
Daniel@0 476
Daniel@0 477 <P>
Daniel@0 478 It's true. dot -Grankdir=LR rotates record nodes so that their top level
Daniel@0 479 fields are still listed across levels. rankdir=LR has no effect in neato.
Daniel@0 480 One workaround is
Daniel@0 481 <A HREF="info/shapes.html#html">
Daniel@0 482 HTML-like records</A> (they don't rotate; the downside is that
Daniel@0 483 you have to write in XML). Another workaround is to enclose
Daniel@0 484 record labels in { } to rotate/unrotate the record contents. See also,
Daniel@0 485 <A HREF="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnhfact/html/hfactor8_5.asp">How To Avoid Foolish Consistency</A>
Daniel@0 486 by Scott Berkun (Microsoft Corp.)
Daniel@0 487 <P>
Daniel@0 488 <A name=Q14 HREF=#Q14>
Daniel@0 489 <B>Q14</A>. How can I print a big graph on multiple pages?</B>
Daniel@0 490
Daniel@0 491 <P>
Daniel@0 492 The <tt>page</tt> attribute, if set, tells Graphviz to print the
Daniel@0 493 graph as an array of pages of the given size. Thus, the graph
Daniel@0 494 <pre>
Daniel@0 495 digraph G {
Daniel@0 496 page="8.5,11";
Daniel@0 497 ...
Daniel@0 498 }
Daniel@0 499 </pre>
Daniel@0 500 will be emitted as 8.5 by 11 inch pages. When printed, the
Daniel@0 501 pages can be tiled to make a drawing of the entire graph.
Daniel@0 502 At present, the feature only works with PostScript output.
Daniel@0 503 <P>
Daniel@0 504 Alternatively, there are various tools and viewers which will take
Daniel@0 505 a large picture and allow you to extract page-size pieces, which can
Daniel@0 506 then be printed.
Daniel@0 507 <P>
Daniel@0 508 <A name=Q15>
Daniel@0 509 <B>Q. When I have a red edge it shows up as a
Daniel@0 510 solid red in PNG and GIF formats, but has a
Daniel@0 511 black border when rendered to JPEG. </B>
Daniel@0 512 </A>
Daniel@0 513 <P>
Daniel@0 514 This is an artifact of JPEG's lossy
Daniel@0 515 compression algorithm. JPEG isn't very good
Daniel@0 516 for line drawings. PNG is bitmap format of
Daniel@0 517 choice. John Ellson wants to deprecate and
Daniel@0 518 eventually remove the JPEG driver, but North
Daniel@0 519 is reluctant to change anything that people
Daniel@0 520 might already rely on.
Daniel@0 521 <P>
Daniel@0 522 <A name=Q16 HREF=#Q16>
Daniel@0 523 <B>Q16</A>. How can I get custom shapes or images in my graph?</B>
Daniel@0 524
Daniel@0 525 <P>
Daniel@0 526 Please see the
Daniel@0 527 <A HREF="http://www.graphviz.org/Documentation/html/shapehowto.html">
Daniel@0 528 Shape HowTo</A> for some approaches. There is no easy way to create
Daniel@0 529 custom shapes that work with dot/neato, dotty
Daniel@0 530 (Unix or MS-Windows) and Grappa (the Java
Daniel@0 531 front end), because they don't share any universal back end structure.
Daniel@0 532 We're thinking about it.
Daniel@0 533 <P>
Daniel@0 534 <A name=Q17>
Daniel@0 535 <B>Q. Sometimes in dotty, right mouse click shows the global menu
Daniel@0 536 but none of the items can be selected.</B>
Daniel@0 537 </A>
Daniel@0 538 <P>
Daniel@0 539 Check that the NUMLOCK key is off. It's a
Daniel@0 540 <A HREF="http://www.research.att.com/~erg/graphviz/bugs/b524.html">
Daniel@0 541 known bug</A>.
Daniel@0 542 <P>
Daniel@0 543 <A name=Q18 HREF=#Q18>
Daniel@0 544 <B>Q18</A>. Why does dotty report a syntax error on a legal dot file?</B>
Daniel@0 545
Daniel@0 546 <P>
Daniel@0 547 Typically this error is reported as:
Daniel@0 548 <pre>
Daniel@0 549 >> graph parser: syntax error near line 14
Daniel@0 550 >> context: >>> <<< digraph G {
Daniel@0 551 >> dotty.lefty: giving up on dot
Daniel@0 552 >> dotty.lefty: graph that causes dot
Daniel@0 553 >> dotty.lefty: to fail has been saved in file dottybug.dot
Daniel@0 554 </pre>
Daniel@0 555 Probably there is a command in your shell environment (such as
Daniel@0 556 .alias or .profile) that does output even for non-interactive shells.
Daniel@0 557 When this occurs, those characters go in the pipe to the dot parser
Daniel@0 558 and cause this problem. An easy check is whether other users have
Daniel@0 559 the same problem.
Daniel@0 560 <P>
Daniel@0 561 <A name=Q20>
Daniel@0 562 <B>Q. How can I get some display feature (such
Daniel@0 563 as bold lines) in dotty?</B>
Daniel@0 564 </A>
Daniel@0 565 <P>
Daniel@0 566 <A NAME="dotty_note">Dotty</A> has not really changed for many years. Therefore, there are
Daniel@0 567 myriad features available in Graphviz which it cannot handle.
Daniel@0 568 In some cases, you can use
Daniel@0 569 <A HREF="http://www.research.att.com/~john/Grappa/">Grappa</A>
Daniel@0 570 or <A HREF="http://www.graphviz.org/webdot/">webdot</A>
Daniel@0 571 for display instead of dotty.
Daniel@0 572 For example, Grappa has generalized polygons
Daniel@0 573 (<tt>node [shape=polygon]</tt>) that dotty lacks.
Daniel@0 574 There are additional interactive viewers available. For example, see
Daniel@0 575 <A HREF="http://www.graphviz.org/Resources.php">Graphical Interfaces</A>
Daniel@0 576 and <A HREF="http://www.graphviz.org/About.php">Viewers</A>. If you
Daniel@0 577 are using Mac OS X, the <A HREF="http://www.pixelglow.com/graphviz/">Mac
Daniel@0 578 version</A> of Graphviz has a highly recommended GUI.
Daniel@0 579 <P>
Daniel@0 580 If the display attribute that you need isn't there already, in dotty,
Daniel@0 581 there's probably no easy way to do it except by rolling up
Daniel@0 582 your sleeves and hacking the dotty code (a lefty script) that
Daniel@0 583 interprets and renders graphical attributes. This is problematic
Daniel@0 584 for the same reason as above: there's no universal low-level driver
Daniel@0 585 layer shared across all the Graphviz tools. We recently added an
Daniel@0 586 intermediate rendering language to the layout tools, but the
Daniel@0 587 various front ends don't use it yet. This would be a good project
Daniel@0 588 for someone who wants to get involved here (along with porting
Daniel@0 589 dotty to GTK.)
Daniel@0 590 <P>
Daniel@0 591 <A name=Q21>
Daniel@0 592 <B>Q. How can I get rid of the little circles on
Daniel@0 593 edges ("edge handles") in dotty?</B>
Daniel@0 594 </A>
Daniel@0 595 <P>
Daniel@0 596 Edit the file dotty.lefty and change the
Daniel@0 597 line that says: 'edgehandles' = 1; to 'edgehandles' = 0;
Daniel@0 598 it's around line 110.
Daniel@0 599 <P>
Daniel@0 600 <A name=Q22>
Daniel@0 601 <B>Q. I already have all the coordinates for the
Daniel@0 602 nodes and edges of my graph and just want to
Daniel@0 603 use dot, neato, or dotty to render it. How?</B>
Daniel@0 604 </A>
Daniel@0 605 <P>
Daniel@0 606 Put the graph with layout attributes into a dot
Daniel@0 607 file.
Daniel@0 608
Daniel@0 609 Then run <tt>neato -s -n2</tt>. For example:
Daniel@0 610 <pre>
Daniel@0 611 neato -s -n2 -Tgif file.dot -o file.gif
Daniel@0 612 </pre>
Daniel@0 613 Note that if an edge does not have a <TT>pos</TT> attribute
Daniel@0 614 defined, neato will perform whatever edge routing it would
Daniel@0 615 normally do. All of the usual backend attributes (<TT>size</TT>,
Daniel@0 616 <TT>overlap</TT>, <TT>page</TT>, etc.) are available.
Daniel@0 617 <P>
Daniel@0 618 <A name=Q23>
Daniel@0 619 <B>Q. I already have all the coordinates for the
Daniel@0 620 nodes, and I want dot or neato to route the edges.</B>
Daniel@0 621 </A>
Daniel@0 622 <P>
Daniel@0 623 It's not really too convenient to use dot for this.
Daniel@0 624 It is possible to use neato for this,
Daniel@0 625 running neato -s -n For example:
Daniel@0 626 <pre>
Daniel@0 627 neato -s -n -Tgif file.dot -o file.gif
Daniel@0 628 </pre>
Daniel@0 629 neato will use the node positions, but use its technique
Daniel@0 630 for routing the edges. There are several things to note. First,
Daniel@0 631 the neato edge router is different from dot's. Without the built-in
Daniel@0 632 top-down bias, it doesn't do as good a job of avoiding edge overlaps
Daniel@0 633 and, at present, it doesn't handle spline multi-edges at all. Second, by
Daniel@0 634 default, neato uses straight lines as edges. To get spline routing,
Daniel@0 635 you have to specify -Gsplines=true. And this will only work if none of
Daniel@0 636 the nodes overlap. Since the input graph supplies fixed node positions,
Daniel@0 637 it is the user's task to insure this.
Daniel@0 638 <P>
Daniel@0 639 <A name=Q24>
Daniel@0 640 <B>Q. I already have all the coordinates for the
Daniel@0 641 nodes and edges of my graph and just want to
Daniel@0 642 use dotty to render it. How?</B>
Daniel@0 643 </A>
Daniel@0 644 <P>
Daniel@0 645 Just run dotty on it. Dotty will use the given pos attributes.
Daniel@0 646 <P>
Daniel@0 647 <A name=Q25 HREF=#Q25>
Daniel@0 648 <B>Q25</A>. Same as above, but I have only node coords, not edges.</B>
Daniel@0 649
Daniel@0 650 <P>
Daniel@0 651 <tt>neato -n</tt> is some help, but neato doesn't handle
Daniel@0 652 spline-based parallel edges.
Daniel@0 653 <P>
Daniel@0 654 <A name=Q26 HREF=#Q26>
Daniel@0 655 <B>Q26</A>. How can I make client-side image maps?</B>
Daniel@0 656
Daniel@0 657 <P>
Daniel@0 658 Use the -Tcmap command line option (only version 1.8.9 and beyond!)
Daniel@0 659 <P>
Daniel@0 660 <A name=Q27 HREF=#Q27>
Daniel@0 661 <B>Q27</A>. Why aren't my server-side maps being recognized? I've checked the HTML!</B>
Daniel@0 662
Daniel@0 663 <P>
Daniel@0 664 Make sure that your server has map files enabled. For example, if running
Daniel@0 665 apache, check that httpd.conf has a line like the following:
Daniel@0 666 <pre>
Daniel@0 667 AddHandler imap-file map
Daniel@0 668 </pre>
Daniel@0 669 and that it is not commented out!
Daniel@0 670 <P>
Daniel@0 671 <A name=Q28>
Daniel@0 672 <B>Q. I've installed Debian Graphviz and it works just fine on the command line,
Daniel@0 673 but when I execute a Perl/CGI script through Apache, no output is generated.</A>
Daniel@0 674 For example, the code
Daniel@0 675 <tt>
Daniel@0 676 system("/usr/local/bin/dot -Tpng /tmp/tree.dot -o /tmp/tree.png");
Daniel@0 677 </tt>
Daniel@0 678 produces no file <tt>/tmp/tree.png</tt>.</B>
Daniel@0 679 <P>
Daniel@0 680 As best as we can tell, dot dies with no stdout or stderr messages on Debian
Daniel@0 681 systems when run from an Apache cgi program
Daniel@0 682 with no HOME set. The workaround is to provide a HOME directory in the
Daniel@0 683 Apache userid's environment.
Daniel@0 684 <P>
Daniel@0 685 Someone has also suggested using the
Daniel@0 686 <A HREF="http://search.cpan.org/search?query=graphviz&amp;mode=all">
Daniel@0 687 Perl module for Graphviz</A>.
Daniel@0 688 <P>
Daniel@0 689 <A name=Q29 HREF=#Q29>
Daniel@0 690 <B>Q29</A>. How can I get 3D output?</B>
Daniel@0 691
Daniel@0 692 <P>
Daniel@0 693 The Graphviz authors have qualms about the gratuitous use of 3D.
Daniel@0 694 <p>
Daniel@0 695 Nonetheless, dot -Tvrml generates VRML files. There's no Z coordinate
Daniel@0 696 layout - you specify Z coords yourself in the <tt>z</tt> attribute of nodes,
Daniel@0 697 and the Z coordinates of edges are interpolated. If someone
Daniel@0 698 contributes a driver for a newer, more useful format (OpenGL Performer
Daniel@0 699 scene graphs? Open Scene Graphs? Java3D programs?) we'd like to try it.
Daniel@0 700 <p>
Daniel@0 701 neato internally supports layouts in higher dimensions through the <tt>dim</tt>
Daniel@0 702 attribute, e.g. <tt>neato -Gdim=7</tt> but there's no way to get the output
Daniel@0 703 unless you invoke neato as a library and inspect ND_pos(n)[i]
Daniel@0 704 where n is a pointer to the relevant node.
Daniel@0 705 This would need some (minor) driver work and a good 7-dimensional viewer. Well,
Daniel@0 706 <tt>dim=3</tt> ought to be possible.
Daniel@0 707
Daniel@0 708 <H2>Problems</H2>
Daniel@0 709 <A name=Q30 HREF=#Q30>
Daniel@0 710 <B>Q30</A>. How can I avoid node overlaps in neato?</B>
Daniel@0 711
Daniel@0 712 <P>
Daniel@0 713 Use the graph attribute <A HREF="info/attrs.html#d:overlap"><tt>overlap</tt></A>.
Daniel@0 714 <P>
Daniel@0 715 <A name=Q31 HREF=#Q31>
Daniel@0 716 <B>Q31</A>. How can I avoid node-edge overlaps in neato?</B>
Daniel@0 717
Daniel@0 718 <P>
Daniel@0 719 Use the <tt>overlap</tt> attribute to leave room among the nodes, then
Daniel@0 720 use <tt>-Gsplines=true</tt>.
Daniel@0 721 <pre>
Daniel@0 722 neato -Goverlap=... -Gsplines=true -Gsep=.1
Daniel@0 723 </pre>
Daniel@0 724 <P>
Daniel@0 725 The <tt>sep</tt> argument is the node-edge separation as
Daniel@0 726 a ratio of a node's bounding box. That is, <tt>sep=.1</tt> means
Daniel@0 727 each node is treated as though it is 1.1 times larger than it is.
Daniel@0 728 The actual value may require some tinkering.
Daniel@0 729 (Don't ask why this isn't just a constant!) Note that this option really
Daniel@0 730 slows down neato, so should be used sparingly and only
Daniel@0 731 with modest-sized graphs.
Daniel@0 732 <P>
Daniel@0 733 <A name=Q32 HREF=#Q32>
Daniel@0 734 <B>Q32</A>. Neato runs forever on a certain example.</B>
Daniel@0 735
Daniel@0 736 <P>
Daniel@0 737 First, how big is your graph? Neato is a quadratic algorithm, roughly
Daniel@0 738 equivalent to statistical multidimensional scaling. If you
Daniel@0 739 feed it a graph with thousands of nodes and edges, it can easily take
Daniel@0 740 hours or days. The first thing to check is to run <tt>neato -v</tt> to
Daniel@0 741 get a trace of the output. If the numbers you see are generally
Daniel@0 742 getting smaller, the layout is just taking a long time. You can set
Daniel@0 743 certain parameters, such as <tt>epsilon</tt> or <tt>maxiter</tt> to
Daniel@0 744 shorten the layout time, at the expense of layout quality. But if your
Daniel@0 745 graph is big, who's going to notice?
Daniel@0 746 <P>
Daniel@0 747 If you see
Daniel@0 748 the numbers repeating, or fluctuating up and down, then neato is
Daniel@0 749 cycling, especially if your graph is small.
Daniel@0 750 This should never happen by default for versions later than 1.13. If it
Daniel@0 751 does, please report it as a bug.
Daniel@0 752 <P>
Daniel@0 753 If you are using an earlier version of neato, or you used <tt>mode=KK</tt>,
Daniel@0 754 cycling is indeed possible. This cycling is very sensitive to the
Daniel@0 755 initial layout. By using the <tt>start</tt> attribute, for example,
Daniel@0 756 <pre>
Daniel@0 757 neato -Gstart=3
Daniel@0 758 neato -Gstart=rand
Daniel@0 759 </pre>
Daniel@0 760 the cycling will most likely disappear. Or you can employ the parameters used
Daniel@0 761 for large graphs to stop the layout earlier:
Daniel@0 762 <pre>
Daniel@0 763 neato -Gepsilon=.01
Daniel@0 764 neato -Gmaxiter=500
Daniel@0 765 </pre>
Daniel@0 766 <P>
Daniel@0 767 Note that, if you have a large graph, the generation of edges as splines
Daniel@0 768 is a cubic algorithm, so you would do well to avoid using <tt>splines=true</tt>.
Daniel@0 769 (This commment applies to circo, fdp and twopi as well.)
Daniel@0 770 <P>
Daniel@0 771 <A name=Q33 HREF=#Q33>
Daniel@0 772 <B>Q33</A>. Edge label placement in neato is bad.</b>
Daniel@0 773
Daniel@0 774 <p>
Daniel@0 775 Difficult problem. We're working on it.
Daniel@0 776 If anyone has some general
Daniel@0 777 label placement code (e.g. a simulated annealer based on the Marks et al.
Daniel@0 778 technique in <I>Graphics Gems IV</I>), please get in touch.
Daniel@0 779 <P>
Daniel@0 780 <A name=Q34 HREF=#Q34>
Daniel@0 781 <B>Q34</A>. Dot runs forever on a certain example.</B>
Daniel@0 782
Daniel@0 783 <p>
Daniel@0 784 Try dot -v to observe its progress.
Daniel@0 785 <p>
Daniel@0 786 Note that it's possible to make graphs whose layout or even parsing
Daniel@0 787 is quadratic in the input size. For example, in dot,
Daniel@0 788
Daniel@0 789 <pre>
Daniel@0 790 digraph G {
Daniel@0 791 a -&gt; b -&gt; c -&gt; .... -&gt; x -&gt; y -&gt; z
Daniel@0 792 a -&gt; z
Daniel@0 793 b -&gt; z
Daniel@0 794 c -&gt; z
Daniel@0 795 /* and so on... */
Daniel@0 796 x -&gt; z
Daniel@0 797 }
Daniel@0 798 </pre>
Daniel@0 799
Daniel@0 800 The total edge length (therefore the layout time) of
Daniel@0 801 this as a ranked graph is quadratic in the number of nodes.
Daniel@0 802
Daniel@0 803
Daniel@0 804 You probably won't encounter the following, but it is also possible
Daniel@0 805 to construct graphs whose parsing takes quadratic time in the number
Daniel@0 806 of attributes, by appending attributes to nodes and edges after the
Daniel@0 807 graph has been loaded. For example:
Daniel@0 808
Daniel@0 809 <pre>
Daniel@0 810 digraph G {
Daniel@0 811 /* really big graph goes here...with N+1 nodes */
Daniel@0 812 n0 -&gt; n1 -&gt; ... -&gt; nN;
Daniel@0 813
Daniel@0 814 n0 [attr0="whatever",
Daniel@0 815 attr1="something else",
Daniel@0 816 /* and so on with many more attributes */
Daniel@0 817 attrM="something again"]
Daniel@0 818 }
Daniel@0 819 </pre>
Daniel@0 820 When an attribute first appears, each object is visited with possible cost
Daniel@0 821 proportional to the number of previously declared attributes. Thus,
Daniel@0 822 the running time for the above would be <I>cN</I> O(<I>M</I>)
Daniel@0 823 for some constant <I>c</I>. If there is any concern about this, the
Daniel@0 824 graph should specify the attributes first before declaring nodes or
Daniel@0 825 edges. In practice, this problem is neglible.
Daniel@0 826 <P>
Daniel@0 827 <A name=Q34a>
Daniel@0 828 <B>Q. Twopi runs forever on a certain example.</B>
Daniel@0 829 </A>
Daniel@0 830 <p>
Daniel@0 831 Is your graph is large (many thousands of edges),
Daniel@0 832 and did you set <pre>splines=true</pre>? It takes
Daniel@0 833 a lot of cycles to fit all those splines!
Daniel@0 834 <p>
Daniel@0 835 <A name=Q35>
Daniel@0 836 <B>Q. Neato has unnecessary edge crossings, or has missed an
Daniel@0 837 obvious chance to make a much nicer layout.</B>
Daniel@0 838 </A>
Daniel@0 839 <P>
Daniel@0 840 Neato and all similar virtual physical model algorithms rely
Daniel@0 841 on heuristic solutions of optimization problems. The better
Daniel@0 842 the solution, the longer it takes to find. Unfortunately, it
Daniel@0 843 is also possible for these heuristics to get stuck in local
Daniel@0 844 minima. Also, it is heavily influenced by the initial position
Daniel@0 845 of the nodes. It is quite possible that if you run neato again,
Daniel@0 846 but with a different random seed value,
Daniel@0 847 or more iterations, you'll get a better layout. For example:
Daniel@0 848 <pre>
Daniel@0 849 neato -Gstart=5 file.dot -Tps -o file.ps
Daniel@0 850 neato -Gepsilon=.0000001 file.dot -Tps -o file.ps
Daniel@0 851 </pre>
Daniel@0 852 <P>
Daniel@0 853 In particular, note that there are no guarantees that neato will produce
Daniel@0 854 a planar layout of a planar graph, or expose all or most of a graph's
Daniel@0 855 symmetries.
Daniel@0 856 <P>
Daniel@0 857 <A name=Q36 HREF=#Q36>
Daniel@0 858 <B>Q36</A>. Webdot doesn't work.</B>
Daniel@0 859
Daniel@0 860 <P>
Daniel@0 861 We assume you're using Apache and have <A HREF="http://www.tcl.tk/">TCL</A> installed.
Daniel@0 862 If you don't, it's probably better to just use the
Daniel@0 863 <A HREF="http://www.graphviz.org/Misc/webdot.pl">
Daniel@0 864 webdot perl script</A>.
Daniel@0 865 <P>
Daniel@0 866 To debug webdot, first test whether <tt>tclsh</tt> can load the
Daniel@0 867 Tcldot shared library. Try:
Daniel@0 868 <pre>
Daniel@0 869 $ tclsh
Daniel@0 870 % load <b>$prefix</b>/lib/graphviz/libtcldot.so.0
Daniel@0 871 %
Daniel@0 872 </pre>
Daniel@0 873 where <b>$prefix</b> is the installation prefix for graphviz; usually /usr
Daniel@0 874 or /usr/local.
Daniel@0 875 <p>
Daniel@0 876 Then test whether webdot runs from a shell command. (With webdot we provide
Daniel@0 877 a helper script scaffold.tcl or scaffold.sh that sets up an environment
Daniel@0 878 like the one Apache provides.) For example
Daniel@0 879 <pre>
Daniel@0 880 $ scaffold.tcl >out.gif
Daniel@0 881 can't read "LIBTCLDOT": no such variable
Daniel@0 882 while executing
Daniel@0 883 "file mtime $LIBTCLDOT"
Daniel@0 884 invoked from within
Daniel@0 885 "set t1 [file mtime $LIBTCLDOT]"
Daniel@0 886 (file "cgi-bin/webdot" line 67)
Daniel@0 887 invoked from within
Daniel@0 888 "source cgi-bin/webdot
Daniel@0 889 "
Daniel@0 890 (file "scaffold.tcl" line 22)
Daniel@0 891 </pre>
Daniel@0 892 The above is a strong clue that webdot is not configured properly.
Daniel@0 893 <P>
Daniel@0 894 Finally, test whether webdot runs as a cgi-bin program.
Daniel@0 895 It may help to examine the cgi-bin environment using a
Daniel@0 896 simple cgi-bin tcl script like:
Daniel@0 897 <pre>
Daniel@0 898 #!/bin/env tclsh
Daniel@0 899 puts "Content-type: text/plain"
Daniel@0 900 puts ""
Daniel@0 901 foreach e [lsort [array names env]] {puts "$e: $env($e)"}
Daniel@0 902 </pre>
Daniel@0 903 Save this script as .../cgi-bin/test.tcl, make it executable, then
Daniel@0 904 look at: <a href="http://localhost/cgi-bin/test.tcl">http://localhost/cgi-bin/test.tcl</a>
Daniel@0 905 <P>
Daniel@0 906 Also, if you see something like:
Daniel@0 907 <pre>
Daniel@0 908 WebDot Error:
Daniel@0 909
Daniel@0 910 Response Code = 403
Daniel@0 911 </pre>
Daniel@0 912 This usually means that webdot ran succesfully, but was not able
Daniel@0 913 to fetch the remote graph from the URL you gave as an argument.
Daniel@0 914 The reason is probably that your server is behind a firewall that
Daniel@0 915 blocks the webdot server, so it cannot get the graph file.
Daniel@0 916 You can either change firewall permissions, put the graph on a
Daniel@0 917 different server, or install webdot locally so you don't need a
Daniel@0 918 remote server to fetch your graph data.
Daniel@0 919 <P>
Daniel@0 920 It would be nice if someone hacked webdot to take the contents
Daniel@0 921 of a graph as a cgi-bin argument, so it wouldn't need
Daniel@0 922 permission to fetch a graph remotely.
Daniel@0 923 This is left as an exercise for the Open Source Community.
Daniel@0 924 <P>
Daniel@0 925 <A name=Q37 HREF=#Q37>
Daniel@0 926 <B>Q37</A>. I have "Font not found" errors, or text labels missing in webdot.</B>
Daniel@0 927
Daniel@0 928 <P>
Daniel@0 929 Firstly, recent versions of graphviz will use fontconfig if it is available
Daniel@0 930 on your platform. With fontconfig, this error should not occur, so you
Daniel@0 931 may want to see if an upgrade to graphviz is available, or if a rebuild
Daniel@0 932 will add fontconfig support.
Daniel@0 933 <p>
Daniel@0 934 If fontconfig is not available then graphviz tries to resolve fontnames
Daniel@0 935 to fontpaths itself, and uses DOTFONTPATH (or GDFONTPATH) to indicate where it should look.
Daniel@0 936 <p>
Daniel@0 937 For copyright reasons, Graphviz doesn't come with its own fonts.
Daniel@0 938 On a Windows machine, it knows to search in <tt>C:\Windows\Fonts</tt>.
Daniel@0 939 On a Unix machine, you need to set up a directory that contains
Daniel@0 940 Truetype fonts. You can get a copy of some fonts
Daniel@0 941 <A HREF="http://www.graphviz.org/pub/graphviz/webfonts-1.0-5.noarch.rpm">here</A>.
Daniel@0 942 <P>
Daniel@0 943 The default DOTFONTPATH is:
Daniel@0 944 <pre>
Daniel@0 945 #define DEFAULT_FONTPATH "/usr/X11R6/lib/X11/fonts/TrueType:/usr/X11R6/lib/X11/fonts/truetype:/usr/X11R6/lib/X11/fonts/TTF:/usr/share/fonts/TrueType:/usr/share/fonts/truetype:/usr/openwin/lib/X11/fonts/TrueType:/usr/X11R6/lib/X11/fonts/Type1"
Daniel@0 946 </pre>
Daniel@0 947 If your fonts are somewhere else, then you must set that directory in
Daniel@0 948 the webdot script, or recompile Graphviz with the correct DEFAULT_FONTPATH
Daniel@0 949 (or set <tt>fontpath="/your/font/directory"</tt> in every graph you lay out,
Daniel@0 950 but that's pretty clumsy.)
Daniel@0 951 <P>
Daniel@0 952 <A name=Q38 HREF=#Q38>
Daniel@0 953 <B>Q38</A>. My browser doesn't recognize SVG.</B>
Daniel@0 954
Daniel@0 955 <P>
Daniel@0 956 The correct MIME type for svg images is: <tt>image/svg+xml</tt> (note "+" not "-").
Daniel@0 957 <P>
Daniel@0 958 SVG is not built into all browsers; you can get
Daniel@0 959 <A HREF="http://www.adobe.com/svg/viewer/install/main.html">plugins</A>
Daniel@0 960 from Adobe for Windows, Linux and some other operating systems.
Daniel@0 961 <A HREF="http://www.mozilla.com/firefox/">
Daniel@0 962 Firefox 1.5</A> has a <A href="http://developer.mozilla.org/en/docs/SVG_in_Firefox_1.5">large subset of SVG</A> and renders graphviz -Tsvg output
Daniel@0 963 though until graphviz 2.8, the fonts may be too large (thanks for
Daniel@0 964 Phil Colbourne at the RailCorp of New South Wales for this advice).
Daniel@0 965 <P>
Daniel@0 966 For help with embedding SVG in HTML pages, see
Daniel@0 967 <A HREF="http://www.graphviz.org/webdot/svgembed.html">here</A>.
Daniel@0 968 <P>
Daniel@0 969 There are several good standalone viewers and editors for SVG.
Daniel@0 970 We like <A HREF="http://www.inkscape.org">inkscape</A>.
Daniel@0 971 <A HREF="http://www.gnome.org/projects/evince/">evince</A>
Daniel@0 972 is the standard Gnome document viewer that handles SVG, at least
Daniel@0 973 since version 0.5 (though Phil C. reports output is blurred)
Daniel@0 974 (see also <A HREF="">eog</A> (Eye of Gnome)).
Daniel@0 975 Commercial tools like Adobe Illustrator and Microsoft Visio
Daniel@0 976 can import SVG (the better to deal with your content, my dear!)
Daniel@0 977 If you are using an older (less bloated) Unix system, you
Daniel@0 978 may find tools like <A HREF="http://xml.apache.org/batik/">Batik</A>
Daniel@0 979 (an SVG renderer in Java) or <A HREF="http://www.sodipodi.com">sodipodi</A>
Daniel@0 980 useful, though it seems they are no longer very actively maintained.
Daniel@0 981 sodipodi is faster but both make sharp images - isn't that the
Daniel@0 982 beauty of path-based graphics?
Daniel@0 983 <P>
Daniel@0 984 <A name=Q39>
Daniel@0 985 <B>Q39. libexpat is reported as containing a virus or as a security hole.
Daniel@0 986 Is this a real problem?</B>
Daniel@0 987 </A>
Daniel@0 988 <P>
Daniel@0 989 No, this is a false positive reported by various security software.
Daniel@0 990 See <A HREF="http://www.pcreview.co.uk/forums/thread-1689630.php">http://www.pcreview.co.uk/forums/thread-1689630.php</A> or
Daniel@0 991 <A HREF="http://spywareblog.com/index.php/2004/11/24/is_libexpat_dll_spyware">http://spywareblog.com/index.php/2004/11/24/is_libexpat_dll_spyware</A>.
Daniel@0 992 <P>
Daniel@0 993 <A name=Q40 HREF=#Q40>
Daniel@0 994 <B>Q40</A>. What is the coordinate transformation between the graph bb and a .png image?</B>
Daniel@0 995 <OL>
Daniel@0 996 <LI>
Daniel@0 997 The bb is expanded by 4 graph-units in all directions (pad) to allow for finite line widths.
Daniel@0 998 <LI>
Daniel@0 999 Then it is zoomed and/or rotated according to -Gviewport, -Gsize, -Glandscape, -Gorientation options.
Daniel@0 1000 At the default scaling of 1:1, one graph unit = 1 point (1/72 inch).
Daniel@0 1001 <LI>
Daniel@0 1002 Then it is paginated, if requested by -Gpage and if the output format supports it. Not the -Tpng renderer, yet.
Daniel@0 1003 <LI>
Daniel@0 1004 Then a margin is added, -Gmargin, in absolute units (inches).
Daniel@0 1005 The top/bottom margin can be set independently of the left/right margin.
Daniel@0 1006 <LI>
Daniel@0 1007 Then it is converted to device units, according to -Gdpi,
Daniel@0 1008 or a dpi value that is given by the output device,
Daniel@0 1009 or a default that is provided by each render.
Daniel@0 1010 There are separate dpi values for x and y to allow for non-square pixels.
Daniel@0 1011 Some renderers invert the Y axis and need an offset to place the
Daniel@0 1012 origin in the top left corner.
Daniel@0 1013 The default dpi for -Tpng is 96dpi (approximating the resolution
Daniel@0 1014 of most computer monitors) so this is where the scaling by 96/72 (4/3)
Daniel@0 1015 comes from.
Daniel@0 1016 </OL>
Daniel@0 1017 <P>
Daniel@0 1018 At the renderer api, plugins have a choice of coordinate representation:
Daniel@0 1019 <UL>
Daniel@0 1020 <LI>
Daniel@0 1021 coordinates in graph-units, and composite transformation data consisting
Daniel@0 1022 of: scaling, rotation, and translation. (used by svg, cairo, ps, renderers)
Daniel@0 1023 <LI>
Daniel@0 1024 coordinates pre-transformed into device units.
Daniel@0 1025 </UL>
Daniel@0 1026 <P>
Daniel@0 1027 <A name=Q41 HREF=#Q41>
Daniel@0 1028 <B>Q41</A>. File associations are broken in Mac OSX. Clicking on a <tt>dot</tt> file doesn't open Graphviz.</B>
Daniel@0 1029 <p>
Daniel@0 1030 The immediate fix is to rebuild the Launch Services database like this:
Daniel@0 1031 <p>
Daniel@0 1032 1. Trash all other versions of Graphviz.app on your system, except for the just installed one. You can use either of these command lines to find it:
Daniel@0 1033 <p>
Daniel@0 1034 <pre>locate Graphviz.app</pre>
Daniel@0 1035 <p>
Daniel@0 1036 or
Daniel@0 1037 <p>
Daniel@0 1038 <pre>find / -name "Graphviz.app"</pre>
Daniel@0 1039 <p>
Daniel@0 1040 2. Run the following command line:
Daniel@0 1041 <p>
Daniel@0 1042 <pre>/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r / </pre>
Daniel@0 1043 <p>
Daniel@0 1044 or
Daniel@0 1045 <p>
Daniel@0 1046 <pre>/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r /Applications</pre>
Daniel@0 1047 <p>
Daniel@0 1048 which deletes the Launch Services database and rebuilds it from existing apps. You may need to sudo to do this.
Daniel@0 1049 <p>
Daniel@0 1050 3. Verify that the Graphviz.app can now open .dot files and Microsoft Word can still open its own .dot files.
Daniel@0 1051 <p>
Daniel@0 1052 One artifact of this will be that Microsoft .dot files may appear with the Graphviz document icon. Unfortunately there doesn't seem any a priori way of getting the system to determine whether an arbitrary .dot file belongs to Word or Graphviz -- you can choose which application to open with by right-clicking or control-clicking on the document icon and choosing the app.
Daniel@0 1053 <p>
Daniel@0 1054 As for why the Launch Services database doesn't automatically register Graphviz,
Daniel@0 1055 we're not entirely sure but suspect this only happens if both conditions
Daniel@0 1056 hold true:
Daniel@0 1057 <p>
Daniel@0 1058 A. The user had installed Microsoft Word.<br>
Daniel@0 1059 B. There is also another version of Graphviz.app present in the system. (Possibly the previous version 1.13 released by Pixelglow Software)<br>
Daniel@0 1060 <A name=Q42 HREF=#Q42><B>Q41</A>. What do all these plugin libraries do?</B>
Daniel@0 1061 <p>
Daniel@0 1062 <ul>
Daniel@0 1063 <li><b>lasi</b> - Adds support for UTF8 characters, beyond ASCII, in postScript output. This table provides a feture comparison of the various PosScript renderers:
Daniel@0 1064 <table>
Daniel@0 1065 <tr>
Daniel@0 1066 <th></th>
Daniel@0 1067 <th>UTF8</th>
Daniel@0 1068 <th>hyperlinks</th>
Daniel@0 1069 <th>human readable PostScript</th>
Daniel@0 1070 </tr>
Daniel@0 1071 <tr>
Daniel@0 1072 <th>-Tps:core</th><td>no</td><td>yes</td><td>++</td>
Daniel@0 1073 </tr>
Daniel@0 1074 <tr>
Daniel@0 1075 <th>-Tps:lasi</th><td>yes</td><td>yes</td><td>+</td>
Daniel@0 1076 </tr>
Daniel@0 1077 <tr>
Daniel@0 1078 <th>-Tps:cairo</th><td>yes</td><td>no</td><td>--</td>
Daniel@0 1079 </tr>
Daniel@0 1080 </table>
Daniel@0 1081 <li><b>gs</b> - Provides support for usershapes in PostScript that can be embedded in all output formats. It interprets the format and renders to a cairo surface. Requires a recent version of ghostscript. (Not needed for PostScript in PostScript)
Daniel@0 1082 <li><b>rsvg</b> - Provides support for usershapes in SVG that can be embedded in all output formats. It interprets the format and renders to a cairo surface. (Not needed for SVG in SVG)
Daniel@0 1083 <li><b>glitz</b> - OpenGL output. But this may not be the right way to dot it, and my glitz plugin is unfinished. Not useful at this time.
Daniel@0 1084 <li><b>ming</b> - Flash output. Was sort of working at one point, not now. Needs development. Might be interesting opportunities for a dynamic graph output. Not useful at this time.
Daniel@0 1085 </ul>
Daniel@0 1086
Daniel@0 1087
Daniel@0 1088 </BODY>
Daniel@0 1089 </HTML>