The DOT graphical back-end

There is currently no graphical editing tool for ERL files. However, there is a graphical back-end outputting (parts of) a schema in the DOT language. The DOT file can then be processed using standard tools from the GraphViz suite of tools, which contains layout generators, GUI editors, etc.

To activate the back-end you must use the --dot option, followed by a (possibly empty) sequence of entity-type identifiers; each of them can be prefixed with -. If the sequence is empty, the whole schema is output. Otherwise, if there are just identifiers prefixed with -, those types are removed from the output. In the other cases, the set of entity types included in the output is built as follows: every identifier without the - prefix adds to the output the type itself, all its supertypes, all the types it owns, and all the types adjacent to the previous ones; every identifier with the - prefix removes the corresponding entity type from the output. Each rule is applied following the order of the parameters on the command line.

This mechanism allows you to print modularly parts of a huge schema: for instance, using ertool --dot -usr -grp -type you can omit the part of the schema handling authorisation. On the contrary, in a large schema you would include the types you are interested in.

A useful feature of DOT (supported by ERtool) is the possibility of associating a URI to a node. ERtool associates to each entity type and relationship type the relative page of the automatically generated documentation. In other words, if everything is set up correctly, you can look with a PDF viewer at your schema, and clicking on a entity or relationship type you can immediately see all the relevant information. If you prefer, you can even generate an image (say, in PNG format) and a client-side image map that will obtain the same effect in a browser.

Making this work is a bit tedious, because the links are local, and thus must be absolute (usually your browser is already running somewhere, so we cannot rely on its current directory being the one we need). However, they are generated relatively to the current directory, so when generating a DOT file you must be in the same directory where you translated the DocBook documentation to HTML. Moreover, the name of the directory containing the documentation must be equal to the id attribute of the root erl element.

Let us work out completely an example (the example works under most Linux distributions). Starting with library.xml, we first generate its documentation and the DOT file:

$ ertool --doc <library.xml >libraryDoc.xml
$ ertool --dot <library.xml >

Then, we produce the HTML documentation. Note that we set explicitly the output directory to match the id attribute of the root erl element:

$ db2html libraryDoc.xml -o library

Finally, assuming GraphViz has been installed successfully, we generate a graphical display:

$ dot -Tps2 < >
$ ps2pdf -sPAPERSIZE=a0

There are several options of dot that can be used to tweak the output (you can even prefer the spring-embedder, neato, but remember to specify the option -Goverlap=false). In the end, the resulting PDF file will contain hyperlinks to the HTML documentation that makes it easy to browse the schema.

Figure 1. An example of automatically laid out entity-relationship diagram with hyperlinked documentation.