SVG Diagrams via Dia: Problems & Solution
tajmone opened this issue · comments
While working on another AsciiDoc project, I've realized that SVG diagrams generated via Dia Diagram Editor are not properly aligning text which wraps across multiple lines (which has a noticeable effect when using monospaced fonts and centered aligned text split across multiple lines).
My dear long-time collaborator @SicroAtGit managed to pin down the root cause of the problem, which boils down to the fact that Dia inserts a newline between the <tspan> text tags which enclose each line of the wrapped text in the Dia generated SVG images — indeed, something that could be easily fixed via some custom S&R script, but ...
While trying to find a solution, I realized that exporting to the cairo-svg format (an alternative SVG export format to Dia's default, not mentioned in the CLI help) generates images which are exempt from the alignment problem.
Furthermore (and most important for us) I also discovered that the Cairo SVG format converts text to vector shapes, thus freeing the diagrams from fonts dependencies.
This last point is quite important for the documents of this project, because so far we've been constrained in our diagrams fonts choices to the limited set of safe fonts which are known to be available on all OSs and devices (i.e. Times New Roman, Arial, Courier New, and a few others). Since SVG diagrams generated via Dia's default SVG export format are rendered as text, the diagrams will look really bad if the specified font is not installed on the end user's machine.
In theory, it should be possible to specify a link to a web-hosted font (e.g. via Google fonts, or other CDNs), or to include an SVG font in the diagram itself, or even to hard-code the font into the HTML document via Data-URIs; but in practice this would require much yak shaving, since none of these options are contemplated in Dia's default export system (i.e. we'd have to either create a custom Dia plugin, or some script to carry out all the kabalistic operations to achieve this).
On the other hand, the Cairo-SVG format solves both the alignment problem as well as that of fonts dependencies, at once and without requiring any obscure magic on our side. Sure, text converted to vector shapes is likely to bloat the final SVG image, but I doubt this is going to be a real problem, partly because diagrams don't usually contain tons of text, but also because we optimize the Dia generated SVG images via SVGO in our toolchain (and we could also tell SVGO to add Zip compression and generate .svgz optimized diagrams).
NOTE — It's worth noting though that images generated via Cairo-SVG export are not 100% identical to the default format, for some features (e.g. 0-width lines and borders) are not supported and might need some changes and workarounds. More testing is required before adopting the alternative format, especially since we use transparent and borderless background boxes to enforce consistent image padding across all output formats.
For the full details of the problem and its possible solutions, and to join the discussion, see the upstream Issue:
New Dia Wiki Page
The above mentioned problems and findings have been resumed in a dedicated Wiki page in this repository, offering with practical examples:
This tutorial page will serve as the main reference for all ALAN projects that use Dia to create diagrams, so that they don't have to provide long explanations on how to setup and use Dia, but just need to link that the commonly shared Wiki page on Dia.
Ready to Update all Diagrams
Now that I've finally managed to solve the above mentioned issues in the other repository, and now that we have a Wiki page explaining these problems and their solutions, I can begin to update the Dia sources in Alan-Docs, so that we can finally enforce custom fonts in these diagrams without fear that they will be seen differently on other machines.
@thoni56 and @AnssiR66, if it's OK with you, I'm also planning to move here any diagrams from other ALAN repositories (e.g. StdLib, and ALAN Italian), so that we might have a single and centralized Dia processing folder, and then just paste the generated SVGs in the images' folder of these repositories — it simply doesn't make sense to have redundant Dia sources and toolchains all over the place, when the ALAN diagrams sources are more useful here, which is the reference project for all ALAN documentation, even if some of these diagrams won't be used by documents in this repo, but elsewhere.
Also, it's not as if we're dealing with hundreds of different diagrams here. But since many of these diagrams share common elements (e.g. the StdLib diagram of classes is built on/from the ALAN classes diagram), and some diagrams from the ALAN Manual are also shared by other docs elsewhere (e.g. the StdLib Manual), I want to avoid having outdated Dia sources in some places. The Dia toolchain is turning out to be more complicated to handle than expected, so I suggest a policy of no redundancy tolerated when it comes to Dia sources!
(well, it would be a good idea to avoid redundancy in general, since the ALAN community is a small network we should just share common assets. I'm still working on creating some shareable toolchain assets, but it's turning out harder than I though.)
I agree about no redundancy ;-) But sometimes locallity of data is more important. But since the toolchain is complicated we definitely do not want to maintain that for multiple repos.
So only question I have is if it would be possible to have Dia sources locally and the toolchain in one place? I am thinking having the Dia sources in the "local" repo and when updating it you need to have the central repo available and "installed". But that depends on how the toolchain works.
As I am not familiar with this issue and don't know the specifics, it's fine for me which ever way you choose to proceed :-). -Anssi
I agree about no redundancy ;-) But sometimes locallity of data is more important. But since the toolchain is complicated we definitely do not want to maintain that for multiple repos.
So only question I have is if it would be possible to have Dia sources locally and the toolchain in one place? I am thinking having the Dia sources in the "local" repo and when updating it you need to have the central repo available and "installed". But that depends on how the toolchain works.
Yes, all good points. The thing is that the Dia project is currently in a bit of a mess, i.e. its split in two separate website and repos, which are not currently in synch with each other (and neither each's website with its repo).
Originally, the intention was to separate the Linux codebase from that of Windows and Mac, but the Windows repo now also offers some Linux builds too, and the Linux repo is trying to become a cross-platform codebase.
Adding to this confusion, the various precompiled binaries of each release are not always available for all OSs, which for us is a problem since it turns out that only Dia v0.97 can produce SVGs without problems, but that (old) version is only available for Windows right now. Also, the Linux repository doesn't use tagged releases, so building a specific release can be hard.
For the above reasons, I though that it would make sense to keep all the Dia source projects and build scripts in a single repository (here) and offer an auto-setup script (already written it), to make things easier for end users, and especially to simplify any Dia updates when a new release will be out that fixes all the current problems — in other words, the choice is to either move the Dia toolchain to an independent Git module, so it can be easily shared by all repos that need it, or just centralize here all diagrams.
Personally, I think it would be simpler to host here all Dia projects, even those concerning images used only by external projects (e.g. the StdLib Manual), because chances are that other tutorials might want to use these images too.
Also, once converted to SVG, these diagrams are rarely going to need editing, so the projects that use them can simply add a script that auto-fetches the latest version of the pre-built SVGs from this repo, via cURL, in case the SVGs were updated.
In most cases, the third party projects which might need these SVGs would just end up being encumbered by the extra Dia sources folder, scripts and their dependencies. It looks more practical to rely on this repository, as if it was an "ALAN images free service", with the added benefit of making these diagrams available to other writers who might need them for their tutorials.
PS: Ciao Anssi! nice to read you again after this long pause.