Chapter 6
Generating Diagrams

ECharts provides the ech2dot translator program for generating ECharts machine diagrams suitable for inclusion in reports, web pages, or presentations. It also provides translators for generating browsable code documentation. The documentation translators are discussed in Section  7.

All these translators share in common their dependence on the open source Graphviz dot program [4] for generating graphical depictions of ECharts machines. The dot program takes as input a text file (with a .dot extension) specifying the constituent nodes and arcs of a directed graph. Its output is a graphical depiction of the graph in one of a number of possible graphical output formats e.g. PostScript, SVG, or PNG. The .dot files themselves are generated from ECharts machine files by the ech2dot translator.

Since there are so many ways to generate ECharts diagrams we’ve included a variety of examples here: Section  6.1 discusses generating diagrams as separate pages and Section  6.2 discusses generating diagrams suitable for embedding in other documents. In Section  6.3 we explain how one can customize a generated diagram if the default output format is unsatisfactory. Finally, in Section  6.4, we discuss how bugs in the current version of dot can affect a diagram’s layout.

Depending on the desired diagram format, some or all of the following open source utilities (not included in the ECharts SDK) are used to assist with diagram generation: dot¹ for laying out and rendering the diagram in a given output format, gs² for converting PostScript to PostScript or PDF (Portable Document Format), eps2pdf³ for converting encapsulated PostScript to PDF, and inkscape⁴ for editing SVG diagrams. All examples here assume the working directory to be runtime/java/src/examples directory of the ECharts SDK. For information on configuring your platform to run ECharts commands like ech2dot see Appendix  A.

6.1 Page Diagrams

Here are a number of examples of generating a diagram as a printable page. In these examples we use the following Unix conventions: the command line prompt is a percent character %, long commands are split over multiple lines using the backslash character \ at the end of a line, and the command line continuation prompt for a command split over multiple lines is the ‘greater than’ character >.

Generate a 8.5 x 11 inch portrait layout diagram in PostScript format with 0.5 inch margins. We post-process the dot output with gs (ghostscript) in order to add explicit page size information.

Generate a 8.5 x 11 inch (US letter) landscape layout diagram in PostScript format with 0.5 inch margins.

Generate a 8.5 x 11 inch landscape layout diagram in PDF (Portable Document Format) with 0.5 inch margins. We post-process the dot output with gs in order to translate to PDF and to add explicit page size information.

Generate a 210 x 297 mm (A4) landscape layout diagram in PDF with 0.5 inch margins.

Generate a 36 x 22 inch portrait layout diagram in PostScript format with increased font size and 1 inch margins. This non-standard poster size page is suitable for printing on a 36 inch wide plotter. We post-process the dot output with gs in order to add explicit page size information.

6.2 Embedded Diagrams

Here are a few examples of how to generate a diagram for embedding in a document page, for example in a web page or a report. In these examples we use the following Unix conventions: the command line prompt is a percent character %, long commands are split over multiple lines using the backslash character \ at the end of a line, and the command line continuation prompt for a command split over multiple lines is the ‘greater than’ character >.

Generate a 6 x 4 inch diagram in PNG (Portable Network Graphics) with increased font size.

Generate a 6 x 4 inch diagram in SVG (Scalable Vector Graphics) format.

Generate a 6 x 4 inch diagram in PostScript format. We post-process the dot output with gs in order to translate to EPS (encapsulated PostScript).

Generate a 6 x 4 inch diagram in PDF. We post-process the gs output with eps2pdf in order to translate to embeddable PDF.

6.3 Customizing the Layout

There are four ways to customize diagrams generated with ech2dot:

1. editing the .dot file output by ech2dot prior to submitting it to dot;
2. generating an SVG format file with dot and then editing the diagram with inkscape.
3. customizing the dot program’s output by overriding layout parameters on the dot command line;
4. customizing the ech2dot program’s output by specifying custom formatters to override the default formatters;

The first option requires an understanding of the Graphviz dot language which we do not discuss here. Instead the interested user is referred to [5] for more information. Generating the SVG file for the second option is discussed in Section  6.1. We discuss the last two options in more detail in the following sections.

6.3.1 Overriding dot Layout

The ech2dot translator generates Graphviz .dot files specifying particular values for layout parameters. Of these, the most relevant for customizing the layout’s appearance are its size and orientation, its label font name and sizes, its layout ratio and its printed caption.

ech2dot specifies the default size for a diagram to be 8 x 10.5 inches with portrait layout. The diagram size and orientation can be overridden via the dot command line as shown in the examples above.

The translator also specifies 8 point font size for edge (transition) and subgraph (state) labels, and the graph (machine) caption, and a 6 point font size for edge head and tail labels. The CourierNew bold font is used for all labels. As shown in the examples above, it is possible to override these font sizes on the command line. It is also possible to override the font name in a similar fashion. For example, to use Helvetica font instead of CourierNew bold:

Note that both a machine’s layout and its states’ layout are dictated via dot’s -G parameter so it is not possible to specify different font names or font sizes for a machine’s caption and its states.

The ech2dot translator also specifies the “fill” layout ratio. For this parameter value, dot attempts to fill as much of the area specified by the diagram’s size as possible. It does this by expanding the size of subgraphs (states) and arcs (transitions). For simple machines with large specified size this can result in oversized nodes. To generate a diagram that satisfies the diagram’s specified size without increasing node size you can try setting the ratio to null. A diagram generated this way will have natural node sizes but is not guaranteed to fill the area specified by the diagram’s size. For example:

The default caption for an ECharts machine diagram is its (unqualified) class name. It is possible to override the caption with arbitrary text via the dot command line as shown in the following example:

The diagram caption can also be overridden by specifying a custom ech2dot formatter as explained in Section  6.3.2.

There are many other layout options available for dot. The interested reader is referred to [5] for more information.

6.3.2 Overriding ech2dot Layout

When ech2dot translates a .ech file to a .dot file it utilizes methods defined in modules called formatters to obtain formatted representations of information included in the .dot file. The formatted information in the .dot file is then included in a machine diagram output by the dot program. For example, a formatter can specify how a machine state or transition declaration is portrayed in a machine diagram.

The ech2dot program permits a user to define their own formatters if the default formatters are not suitable for their purposes. There are three formatter classes that may be overridden by the user:

label formatter

This formatter defines methods for formatting state and transition labels appearing on a machine diagram.

tooltip formatter

This formatter defines methods for formatting tooltips that are embedded in client-side imagemap files output by dot.

URL formatter

This formatter defines methods for formatting URLs that are embedded in client-side imagemap, PostScript, or SVG files output by dot.

As described in the ech2dot command reference in Section  8, there are three command line options available for overriding the three formatter classes: --label-formatter, --tooltip-formatter, and --url-formatter, respectively. The value for each parameter must be a valid formatter (Python) class name. A formatter class is normally a subclass of the parent formatter class translator/lib/dotmachine/DotMachineFormatter.py included in the ECharts SDK. This class provides default definitions for methods that can be overridden by formatter subclasses. To support the default behavior of the ech2dot translator, four formatter subclasses are included with the ECharts SDK in the translator/lib/dotmachine directory:

• DotMachineNullFormatter.py As its name implies, this formatter returns the empty string for all state and transition formatter method calls.
• DotMachineCompleteFormatter.py The methods of this formatter return the complete state or transition definition string as found in the original .ech file.
• DotMachinePartialFormatter.py The methods of this formatter return a partial state or transition definition string as found in the original .ech file. For example, state label strings only include the state name and the submachine class name, but any submachine parameters are excluded.
• DotMachineCommentFormatter.py The methods of this formatter return the user comments associated with a state or a transition.

Here are the default values of the three ech2dot formatters:

6.4 dot Layout Bugs

The open source directed graph layout program dot is used to produce the example machine diagrams included in this manual. The layouts produced by this program are normally excellent, however, the current version of dot (version 2.15) suffers from bugs that cause some transitions to be depicted incorrectly. In particular, there are two problems related to the depiction of a transition referencing the same source and target states i.e. looping transitions:

1. dot does not always correctly depict the machine level a transition is declared at;
2. dot does not always connect a transition to its referenced source or target states.

As an example of both layout problems consider the depiction of Example0021 in Section  3.11. The graphical depiction of the transition in state S1 shows no source state reference. A correct depiction would show the transition source connected to the border of state S1. Furthermore, the transition should be depicted as extending outside S1’s border since the transition is declared in the Example0018 machine, not in the state S1 submachine. The same problems are seen in Example0022, Example0052, Example0054, Example0053, Example0055, Example0056 and Example0058 in Section  3.11, Example0025 in Section  3.10.2, Example0027 in Section  3.12, Example0044 in Section  3.13, Example0029 and Example0030 in Section  3.15, Example0035 in Section  4.5.3, Example0038 and Example0039 in Section  4.7.1, Example0040 in Section  4.7.2, and Example0050 in Section  4.8.