Graph::Easy - Manual

This document tried to answer the most frequently asked questions in relation to Graph::Easy, as well as for the MediaWiki integration.

Question:

Is there an interactive editor or GUI for Graph::Easy?

Answer: [2014-05-25]

No, there is no longer an editor. Sorry.

Question:

What extension should Graph::Easy files have?

Answer: [2006-12-17]

The native format of Graph::Easy is called "txt", as can be seen on the method names (as_txt()) as well as the converter options. And since a graph description in Graph::Easy is just this, text, the file extension used should be .txt.
Some people like to invent their own extension for Graph::Easy files, but this just is a solution in search for a problem, and actually causes more problems, namely:

• There aren't enough two- and three-letter combinations available, so name clashes are unavoidable
• All current modern operating systems know how to handle .txt files, but for an unknown extension no handler is setup/installed
• Likewise, sending .txt files via email etc. already works

Therefore, Graph::Easy textual descriptions should be called what they are: .txt.

Question:

What are the main differences between Graph::Easy and Graphviz?

Answer: [2006-08-20]

Graph::Easy has:

• an easier syntax, that is very human readable/writable and makes thus maintance easier, especially for people unfamiliar with graphviz, HTML or similar languages
• a grid based layouter, which is suited for flowcharts. For complex graphs it can also use graphviz as backend, giving you the best of both worlds.
• is easier to install, needs no compiler, just Perl
• Can output HTML, and ASCII art
• Sizes, widths, lengths and offsets are all given relative, either to some point of reference or the current font-size. This makes the output resolution independend and freely scalable.

Question:

What can Graphviz, that Graph::Easy cannot do?

Answer: [2006-08-06]

Here is a list of things that Graph::Easy has difficulties with, or that are not yet implemented:

• For complex layouts, the layouter easily breaks down.
• The layouter only has one overall strategy (unlike graphviz, where dot, neato and circo all implement wildly different strategies)
• One cannot define a starting point on an edge, edges always start with a plain line.
• Groups (aka subgraphs) cannot yet be nested.
• Some shapes and options (node shape egg, edge lines with more than two lines f.i.) are not yet possible
• There are only 8 different arrow shapes (triangle, box, dot, inv, line, diamond, cross, x)
• Not as many layout influencing options (margins, paddings and spacings are generally missing)

Question:

What can Graph::Easy, that Graphviz cannot do?

Answer: [2006-11-18] Apart from the IMHO easier for humans syntax of the input format, here are the key points:

• Full Unicode support on both input and output (when supported by the output format, all native ones like HTML, SVG and ASCII/Unicode output do). Graphviz has problems when you include "foreign" characters, then you must set the proper font (and hope that it is portable and contains all glyphs your label has)
• Grid-based layouter
• Support for HTML, ASCII and boxart drawing (Unicode) output formats
• You can set text-styles on labels like underline, overline, bold, italic etc
• You can even set these text-styles for parts of a label and mix them, even nest them like so: underlinebold and italic (Implemented in v0.43)
• text-wrap: auto automatically wraps labels (Implemented in v0.43)
• You can set the flow (direction of layout) for the entire graph, and change it on an per-node or even per-edge basis.
• Graphviz doesn't implement the border or edge style "wave". Edge styles involving double lines are non-obvious to create in Graphviz.
• Links are build from two parts, a linkbase and a link. Thus you can easily set a common base part and put the rest per node on it. There are even attributes than build links or titles automatically.
• You can restrict the node length automatically, and make a title automatically show the full node text.
• Edge arrows can have their arrows filled with a different color
• Graph::Easy supports an additional color scheme, w3c. This is also the default. (Color scheme support is implemented in v0.46)

Question:

Are there other differences between Graph::Easy and Graphviz?

Answer: [2006-03-12]

There are other differences which have mainly to do with the output formats and their limitations or advantages. For instance:

• HTML allows text zoom (good for people with bad eyesight, or big monitors), while f.i. raster image formats like PNG only support one fixed size
• Plain text formats like HTML or SVG allow easy indexing of the contents.
• SVG files are truly resolution independend.
• ASCII output lacks many things, but can be read even on a terminal or by a screen reader.

Since Graph::Easy's own layouter can only output HTMl, ASCII or SVG, other formats like PNG or PDF must be created by either using the graphviz backend, or by outputting SVG and then converting this. In the future SVG support by viewing and printer subsystems will hopefully be so good that such "hacks" are no longer required, though.

Question:

Is there a speed difference?

Answer: [2006-03-12]

Graph::Easy might be a bit slower for some things, but is faster for others. In praxis this only matters for huge graphs. For details, please see the benchmark page.

Links open inside the SVG

Question:

When I click a link in an SVG graph, the new page is opened inside the graph, instead of in a new window/tab or even in the same window.

Answer:

This is a Firefox 1.5 bug. Firefox will open links in SVGs by default "inline", and it even ignores attributes like "xlink:show" and "xlink:target".
The bug is reportedly already fixed in the Mozilla codebase, so it should work in the near future in a browser on your system.
In the meantime upgrade Graph::Easy::As_svg, as newer versions contain a workaround for this bug.
See also bug #315389 in the bugzilla.

Text too big

Question:

The text on nodes is to small, or to big, and sometimes even crosses the node border.

Answer:

Please upgrade Graph::Easy::As_svg, this bug has been fixed in v0.18.
You still might see text that is either too big or too small if you use the text-zoom (CTRL plus + or -), Firefox will zoom the font/text, but not the rest of the SVG, thus the graphic quickly becomes garbled.

Graphic corruptions

Question:

I see only garbled graphs, f.i. it has black rectangles or the labels are not properly centered.

Answer:

Make sure you are using the latest version of your browser. Opera 8.5 does only support SVG Tiny, which is not enough to properly display the SVG generated by Graph::Easy. Likewise, Opera 9.0 only supports SVG Basic, which sadly also misses key features like centered text.
Other browsers seem to lack support for CSS-styles inside SVG, and thus will render the fillcolor inside nodes wrongly (the default is black, and the overriden color from the CSS is ignored by these buggy browsers).

Install under Windows

Question:

Can I install and use Graph::Easy under Windows?

Answer:

Yes. You need two things:

• Perl, you can get it from Activestate
• nmake, see here for how to get and install nmake

After installing Perl and nmake, you can install Graph::Easy normally, just replacing "make" with "nmake" in the install instructions:

perl Makefile.PL
nmake
nmake test
nmake install

If you have questions, or found an error on this page, feel free to send me an email. Bugreports should go to rt.cpan.org.