Dia Diagrams - alan-if/alan-docs GitHub Wiki
This Wiki page presents Dia, the open source diagram editor used to create nice SVG diagrams for the Alan-Docs repository and other Alan related projects.
We’ll also present some tips and tricks to make the most of Dia, and discuss some issues which force us to use a specific version of Dia in our toolchain (Dia v0.97).
Dia Diagram Editor is free and open source tool available for Windows, Linux and macOS. It allows to create complex diagrams in an extremely simple manner thanks to a rich library of predefined shapes for flow charts, electronics, and all sorts of diagrams types (too many to mention them all).
We chose Dia for the Alan documentation because it empowers us to create scalable SVG diagrams (ideal for HTML documents) and without having to deal with the low-level complexity of the SVG format. The Dia GUI has a powerful WYSIWYG interface that abstracts away the complexity of designing vector diagrams, focusing on the essential needs for this task.
Furthermore, Dia can also be used as a command line tool to automate the conversion of Dia project files into SVG images (and many other output image formats too), which enables us to seamlessly integrate it into our automated toolchain.
In order to build the diagrams of the Alan-Docs project, you’ll need a specific version of Dia: v0.97 (2009-05-14).
|
|
Dia versions above 0.97 won’t work as expected, because the diagrams rely on specific Cairo-SVG features which have changed in later Dia versions (see Known Issues with Dia v0.97.x below). The problem has to do with zero-width borders, which should not be drawn in the final SVG generated using Cairo-SVG (an undocumented native export filter). Tests under Windows revealed that Dia versions >=0.97.1 draw these zero-width borders, whereas Dia 0.97 correctly ignores them. The problem might be related to the Cairo library version employed, not with Dia itself, and it might affect the Windows edition only (although tests on Linux point to the contrary). If you’re working under Linux or macOS, just check that the final SVG images built using |
|
ℹ️
|
Dia v0.97 is only required to actually convert the You can edit the source diagrams with a more recent version of Dia (I use Dia-0.97.2-2 for editing), thus benefiting from the various bug fixes, improvements and new features. Under Windows, you can unpack locally as many different Dia versions as you wish, since the standalone versions don’t require installation; on other OSs this might not be as easy to achieve. Just make sure that you only add Dia v0.97 to the System PATH, so that scripts will use the correct version. |
Windows users can download pre-compiled binaries of Dia v0.97 from SourceForge:
-
-
dia_0.97_win32.zip— standalone Zip package.
-
For other OSs, you’ll have to either do some scavenging around Dia’s websites and repositories, or build Dia from source.
There are two distinct official Dia websites:
-
https://wiki.gnome.org/Apps/Dia — for latest Linux editions (build from source).
-
http://dia-installer.de — for latest precompiled binaries for Windows, Linux and Mac.
and two official repositories, associated to the above websites:
Unfortunately, these two projects are not well synchronized between each other, and even their websites don’t always mirror the latest state of their source repositories. But since Dia is a well known open source project, just ask the community for help if you can’t find what you’re looking for (you’ll surely get great support).
In any case, we’ll be keeping an eye open for future Dia releases, hoping that a new Dia version will support all the required Cairo SVG features, allowing us to adopt the latest Dia release in the future, instead of sticking to an outdated version.
To illustrate the problems we came across using Dia, we’ll be using a Dia project, the sample.dia file, which can be downloaded from this Wiki.
Here’s our example Dia project, being edited in Dia v0.97.2-2 (2012-07-05):
This example represent a typical diagram element: some text in monospace font that is center-aligned and runs on multiple lines.
It’s important to notice that the diagram contains an invisible background box (zero-width border, background color not drawn) that is slightly bigger than the diagram itself, and which serves to enforce padding around the diagram:
Dia’s native SVG export filter presents various problems:
-
Text alignment is not preserved.
-
The SVG text depends on external fonts.
Here’s the SVG result exporting our project using Dia v0.97.2-2 and the default SVG output format:
You can clearly see that the text in the final SVG is not properly centered.
The reason for this is due to how Dia generates the XML of the SVG image, inserting a new line between the two <tspan> tags representing the text lines:
<tspan x="40" y="30">XXX</tspan>
<tspan x="40" y="53.9889">XXXX</tspan>in fact, if you edit the SVG image source and join together the above lines, like this:
<tspan x="40" y="30">XXX</tspan><tspan x="40" y="53.9889">XXXX</tspan>the text will become center-aligned, as originally intended:
But manually fixing every multi-line text in auto-generated SVG images is not a viable option.
Furthermore, by looking at the XML source of the generate SVG image, we can clearly see that the diagram depends on specific fonts being installed on the end user machine (in our example, the Inconsolata font):
<text font-size="19.1911" style="fill: #000000;text-anchor:middle;font-family:Inconsolata;font-style:normal;font-weight:normal" x="40" y="30">
<tspan x="40" y="30">XXX</tspan>
<tspan x="40" y="53.9889">XXXX</tspan>
</text>This means that there are no guarantees that the final SVG images will be viewed as expected across all devices — if the required font is missing, text elements will break up, being substituted by some default fallback font which is going to have different proportions, resulting in text being too small or too big, unentered and even leaking out of its box.
One solution could be to use only “safe fonts”, i.e. fonts which are expected to be available on all OSs and devices, but this reduces the number of usable fonts to a drastically limited set (Times New Roman, Arial, Verdana, Courier New, and maybe a couple of others), especially for monospace fonts.
But as we’re going to see next, the Cairo SVG export filter allows us to create SVG images in which all text is converted to vector shapes.
Dia supports an alternative SVG export filter: Cairo SVG. This is a powerful (yet undocumented) alternative to the default SVG format.
It’s available in the Dia GUI menus File › Export… and File › Save As, as well as in the command line Dia tool, via the filter type option --filter/-t:
dia -n -t cairo-svg sample.diaAnd here’s the result using Dia v0.97.2-2 and the Cairo SVG output format:
As you can see, the text is now properly center-aligned, but there’s a problem with the invisible Box, where the zero-width border is actually being drawn.
We’ve tried using different Dia releases in the range v0.97.x, and all of them caused the same problem.
It seems like the problem has to do with the Cairo library used by Dia versions >=0.97.1, which don’t accept zero-width borders.
Since Dia doesn’t currently support transparent colors, support of zero-with borders is essential to keep these padding boxes invisible.
Luckily for us, Dia v0.97 doesn’t have this problem, even though it’s a pretty older version (2009) compared to the latest official Dia release (2012).
Finally, the same project exported using Dia v0.97 and the Cairo SVG output format:
Here we can see the text properly centered aligned, and the invisible padding Box is not being drawn in any visible manner (but it’s there, contributing to the diagram size and providing padding).
Also, the generated SVG doesn’t depend on any external fonts for its contents, for all text glyphs have been converted to SVG vector paths:
<path style="fill-rule:nonzero;fill:rgb(100%,100%,100%);fill-opacity:1;stroke-width:0;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(0%,0%,0%);stroke-opacity:1;stroke-miterlimit:10;" d="M -0 -0 L 4 -0 L 4 3.8 L -0 3.8 Z M -0 -0 " transform="matrix(20,0,0,20,0,0)"/>This defintely bloats the size of the generated SVG images, but using an SVG optimizer like SVGO reduces drastically the size of these SVG files (sometimes, up to 50%), making those differences negligible even in complex diagrams packed with dozens of elements.
On the other hand, the Cairo SVG filter grants us total freedom in choosing which fonts to use in our diagrams (including commercial fonts, which can’t be redistributed), without fearing that end users won’t be able to see the diagrams as intended. This means that we can use unconventional fonts, and even dingbats in our diagrams designs.
This tutorial and all its fixes wouldn’t have been possible without the help from Alexander Bolli (@SicroAtGit) who pointed out to me various problems and carried out extensive Dia tests on Linux to find solutions.
You can see the original discussion on Issue 12 at the GitBuch English translation repository.