Graph::Easy - Manual - Output

# Graph::Easy - Manual

## Output Formats and their Limitations

If you haven't done so, please read the Overview first.

This chapter describes the possible output formats and their limitations, strengths and weaknesses.

### Formats

Graph::Easy can create the following output formats:

- txt - a dump of the graph as a textual description, parsable by Graph::Easy::Parser
- graphviz - a dump of the graph in the graphviz format. This can be feed to external programs like dot to generate PNG, SVG etc.
- ASCII - creates an ASCII art "drawing" of the graph
- Box Art - uses Unicode "box drawing" characters to create a textual "drawing"
- HTML - outputs HTML+CSS code (actually a big table) to render the graph in your browser
- SVG - creates Scalable Vector Graphics output

### ASCII

The ASCII output is limited to only two colors, one for the foreground, and one for the background.

      #============================================#
      H                                            v
    +---------+     ........     +---------+     +--------+     +--------+
    | Bautzen | --> : Bonn : --> | Koblenz | --> | Berlin | --> | Kassel |
    +---------+     :......:     +---------+     +--------+     +--------+
      ^               |            ^               ^
      :               +------------+---------------+
      :                            |
      :             +------+       |
      ............. | Ulm  | ------+
                    +------+

The following limitations apply:

- The edge arrows are always rendered open, regardless of the actual arrow style.
- Node shapes with slanted or round borders are not yet supported.
- Edge styles `bold`, `broad` and `wide` are all rendered with '#' and thus look the same.

### Box Art

Works like the ASCII output, but uses Unicode "box drawing" characters instead. This creates gap-less edges, and looks generally much better.
Box art output shares most of the limitations with the ASCII output, except:

- corners on borders look better
- rounded node borders are supported
- the different arrow-styles work
- edge styles `bold`, `broad` and `wide` work

                                    My sample graph

                                                 Test
                                                 label
                ┌···············································┐
                :                                               v
              ┌─────────────┐  label   ▛▀▀▀▀▀▀▜               ┌───────┐
              │     One     │ ───────> ▌ Two  ▐ ▬▬▬▬▬▬▬▬▬▬▬▬> │ Four  │ ···   None
              └─────────────┘          ▙▄▄▄▄▄▄▟               └───────┘
                ║                                Test label
                ║                        ┌╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┐
                v                        ╵                      v
              ┌−−−−−−−−−−−−−┐          ████████               ┏━━━━━━━┓     ┌───────┐
      ┌·······╎    Three    ╎ <══════> █ Five █ ────────────> ┃ Seven ┃ ─── │ Eight │
      :       └−−−−−−−−−−−−−┘          ████████               ┗━━━━━━━┛     └───────┘
      :         ^                        │                                    ^
      :         │                        │                                    │
      : Test    │ Test label             └────────────────────────────────────┘
      : label   v
      :       ┌─────────────┐
      :       │    Sixty    │
      :       │    Six      │
      :       │    and      │
      └······>│    six      │
              └─────────────┘

### HTML

The following table shows the main features and their support in the main browsers.

Feature | Opera | Mozilla Firefox | Konqueror | IE
--- | --- | --- | --- | ---
Node shapes: rounded, circle, ellipse | No | Yes | No | No
Nodes with angled borders: diamond, house, triangle, etc. | No | Yes | Yes | 5.x +
Node shape: point | No | Yes | Yes | 5.x +
Gapless edges | Yes | Yes | Yes | Yes
Padding between graph content and border | Yes | Yes | 3.4 + | No

Here is a sample graph:

My sample graph
|  |  | Test label |  |
| v
|  | > | Five |  |  | > | Seven |  |  |  | Eight |  |  |  | None
|  |  |  | ^
|  | > | Three | < |  |  | One |  | label | > | Two |  |  | > | Four
| ^ |  |  |  | Test label | ^
| Test label |  |  |  |
v
| Six

### SVG

Some SVG renders, notable Opera, do not support center-aligned text. Since this is used to render node labels, these will appear off-center. Likewise, Opera 8.02 does not support `tspan` at all. This means multi-line labels will be missing.
There is nothing that can be done about except for SVG renderes finally supporting the full spec instead of some random subset.

Shape `img` is not supported by SVG since it seems impossible to embed bitmap/raster grafics into a SVG document.

Otherwise, the SVG output is mainly complete. If you notice any feature missing or not working, please open a bug report.

### Graphviz

Graph::Easy also allows the output of Graphviz code, which can be feed to an external program like `dot` or `neato` to create `.png`, `.ps`, `.svg` or many other file formats:

    perl examples/as_graphviz my_graph.txt | dot -Tpng -o graph.png
    perl examples/as_graphviz my_graph.txt | dot -Tsvg -o graph.svg

The output to graphviz does not yet take some features of Graph::Easy into account. The reason is that graphviz works differently than Graph::Easy and at the moment there seems no easy way to implement this. Here is a short list of features that are incomplete:

- nodes that are placed relatively to each other
- multi-celled nodes (labels like "{ A | B }" could emulate this)
- per-node flow directions (flow for the entire graph will work, though)

In addition, the following output styles are not yet supported. These probably can be emulated with some graphviz-fu, but there was not enough time to find out how:

- node border-styles: wave, dot-dot-dash and dot-dash
- edge-styles: double, double-dash, wave, dot-dot-dash and dot-dash
- filled edge arrows with different fill colors
- node shape: point with other point-styles than "circle"

Note thar unlike with the other output methods, Graph::Easy has less control over the layout when outputting graphviz code. Sometimes this improves graph layout, because dot et. al. are not restricted to a grid-like layout, but certain features might be rendered quite differently by dot than by Graph::Easy.
Especially the per-node and per-edge flow and relatively placed nodes will likely be lost in the generated graphviz code.

Please continue with the chapter about the syntax.