Mercurial > hg > camir-aes2014

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

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