Source files to generate the diagram images in SVG using Dia.
Table of Contents
- Folder Contents
- System Requirements and Set-Up
- TODO
- Diagrams List and Preview Links
- Diagrams Info
- Diagrams Previews
branch-model.svgcentral-workflow.svgclone.svg- Images Group: Commit Graphs
commit-graph.svgcommit-graph-with-refs.svgcommit.svg- Images Group: ff
git-objects-hierarchy.svg- Images Group: Git Objects
github-workflow.svgindex.svgintegration-manager-workflow.svgmerge-base-commit.svgpatches-via-email.svg- Images Group: Git & SVN Operations
- Images Group: Rebase
relative-refs.svgrepository-content.svgsha.svg
- External Links
build.sh— converts all*.diaprojects to*.svgimages into../../../docs_src/images/.preview-generator.sh— creates an HTML page to preview generated SVGs:preview.html— not tracked by Git! (need to generate)preview.css— CSS for previewing diagrams.
get-dia.bat— Dia download and unpack script for Windows 10.*.dia— Dia source project files.
To run build.sh you'll need the following dependencies:
In order to edit the diagram's sourcefile, or to run the scripts in this folder, you'll need to install Dia Diagram Editor version 0.97.
Dia is a free and open source cross platform tool for editing diagrams.
IMPORTANT! — Dia versions above
0.97won't work as expected, because the diagrams rely on specific Cairo-SVG features which have changed in later Dia versions (see Issue #12). The problem has to do with zero-width borders, which should not be drawn in the final SVG generated using Cairo-SVG (which is an undocumented native export format).Tests under Windows revealed that Dia versions
>=0.97.1draw these zero-width borders, whereas Dia0.97correctly 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.If you're working under Linux or macOS, just check that the final SVG images built using
build.shdon't contain a thin black border around them — ideally, rebuilding the diagrams shouldn't result in any changed SVGs files in the repository.
Depending on your OS and Dia's setup, you might also need to add to the system PATH the full path to Dia's executable (i.e. the bin/ subfolder of Dia's installation) so that it will be visible the build.sh script used here.
The Dia project is currently a bit messy.
At the time of this writing, the latest official Dia release according to the official websites is version 0.97.2 (2011-12-18), but Dia version 0.97.3 (2014-09-05) for Linux is already available from the GNOME Git repository, although it's not mentioned in either of Dia's websites:
Adding to the confusion, 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:
Older versions of Dia can be downloaded from SourceForge, either as source code or as precompiled binaries for Linux, Mac and Windows:
Linux users might build Dia from source via Git, from the GNOME repository:
Dia version 0.97 might not be available for all OSs, some precompiled binaries will be for 0.97-1, 0.97-2, etc., but as long as it's in the 0.97-x range it should be fine.
Anyhow, what's important here is to ensure that the Dia version used doesn't draw the zero-width borders around the diagrams when exporting to Cairo-SVG.
WIN 10 DOWNLOADER — If you're using Windows 10, you can simply run the following batch script which will download the correct version of Dia and unpack here, into the
./Dia/subfolder:The
build.shscript will autodetect its presence and use itsdia.exebinary, instead of relying on the system PATH. This will prevent conflicts with other versions of Dia that might be present on your system.
The recommended version for Windows is Dia 0.97 (2009-05-14), available from SourceForge:
That's the exact Dia version used to build the diagrams by the project maintainer.
In order to install SVGO you'll need to install Node.js on your system.
Windows users can install Node.js via the Node JS Chocolatey package using the Chocolatey GUI, which simplifies keeping Node always up to date.
- Translate DIA sources filename to English.
- Edit source diagrams:
- Optimize generated SVG images via SVGO.
The following table provides preview links to the generated SVG files in the ../../../docs_src/images/ destination folder.
| DIA source | SVG output |
|---|---|
branch-model.dia |
branch-model.svg |
central-workflow.dia |
central-workflow.svg |
clone.dia |
clone.svg |
commit-graph-with-refs.dia |
commit-graph-with-refs.svg |
commit-graph.dia |
commit-graph.svg |
commit.dia |
commit.svg |
fetch.dia |
fetch.svg |
ff-after.dia |
ff-after.svg |
ff-before.dia |
ff-before.svg |
git-objects-hierarchy.dia |
git-objects-hierarchy.svg |
git-objects.dia |
git-objects.svg |
github-workflow.dia |
github-workflow.svg |
index.dia |
index.svg |
integration-manager-workflow.dia |
integration-manager-workflow.svg |
merge-base-commit.dia |
merge-base-commit.svg |
patches-via-email.dia |
patches-via-email.svg |
pull-rebase.dia |
pull-rebase.svg |
pull.dia |
pull.svg |
push.dia |
push.svg |
rebase-after.dia |
rebase-after.svg |
rebase-before.dia |
rebase-before.svg |
rebase-onto-after.dia |
rebase-onto-after.svg |
rebase-onto-before.dia |
rebase-onto-before.svg |
relative-refs.dia |
relative-refs.svg |
repository-content.dia |
repository-content.svg |
sha.dia |
sha.svg |
svn-dcommit.dia |
svn-dcommit.svg |
svn-rebase.dia |
svn-rebase.svg |
tags.dia |
tags.svg |
The DIA sources in this folder were taken from the bilder_quelldaten/diagramme/ folder of the Git-Buch upstream repository.
diagrams-palette.cifc— ColorImpact 4 palette project.diagrams-palette.html— Palette color spec.diagrams-palette.png— Palette swatches.
The color palette for the diagrams' background colors was redesigned. The original palette contained too many similar (but no identical) colors, so we've reduced the palette entries by adopting a consistent color scheme, free of similar colors redundancy:
Each base color (top row) has a lighter tint counterpart (bottom row). Most diagrams use only base colors; lighter colors are mostly used in diagrams representing before/after transitions, to mark previous states.
There's a methodology behind color usage in the original diagrams, which has been preserved in our changes. A close examination of the diagrams is sufficient to grasp the colors-usage criteria.
NOTE — Some of the above colors are not actually used in any diagrams, but we've kept them in the palette for the sake of color scheme completeness and consistency, and in case they might be needed in the future.
Furthermore, the original palette featured some dark colors that didn't meet the WCAG 2 guidelines on contrast and color requirements (see Issue #15), so the entire color scheme was redesigned from scratch, using color harmonies that produced colors similar to the originals, but not as dark, and ensured that they all pass the color contrast accessibility tests via the WebAIM Contrast Checker:
| contrast ratios | 19:1 | 14.93:1 | 10.82:1 | 10.75:1 | 14.4:1 | 12.91:1 | 15.6:1 |
|---|---|---|---|---|---|---|---|
| base colors | #FDF6B2 |
#FDD1B2 |
#E9A4DE |
#A1BBE5 |
#A9E5A1 |
#BACFCF |
#DEDEDE |
The original diagrams relied on using "monospace" font, which is a generic fallback definition which might lead to different OSs picking different default fonts (although "Courier New" would be usually the default choice, unless the user has specified another font). Similarly, the few diagrams which rely on sanserif fonts were using the "sans" font, which is likely to produce different results on different OSs.
Also, we're using the Cairo-SVG output format (natively supported by Dia, but undocumented) which will convert all text to SVG shapes, freeing the final SVG diagrams from any fonts-dependencies.
We've therefore chosen to use the following fonts for the diagrams:
| category | name | version | author | repo | license |
|---|---|---|---|---|---|
| monospace | Inconsolata | v3.001 |
Raph Levien | GitHub | SIL Open Font License 1.1 |
| sans serif | Open Sans | v1.10 |
Steve Matteson | GitHub | SIL Open Font License 1.1 |
You can also download the required TTF fonts files, individually, directly from the fonts repositories on GitHub:
The above linked TTF fonts are the minimum required font styles. Whether you wish to install the full set of font styles variants and combinations is up to you.
NOTE 1 — The San Serif font is indicated as being licensed under Apache 2.0 on Google Fonts, but in its GitHub repository it's released under the SIL Open Font License 1.1, so we take for good the latter.
NOTE 2 — Unfortunately, the Open Sans GitHub repository doesn't provide version tag nor releases, so it's hard to find/provide direct links to specific versions of the font files.
If you need to rebuild some diagrams, ensure that you've installed the fonts from the Google Fonts or GitHub links provided above because some OSs (e.g. Windows) ship with same-named fonts by different authors, which might produce slightly different results. Ideally, you should install the same exact versions indicated above, to ensure identical results; but it makes more sense to simply install the latest version of the fonts and simply update all diagrams, if these result in differing SVGs.
Under Windows OS, you can safely install those fonts even though already present in the system (as natively shipped fonts), because they will be installed in the User fonts directory, taking precedence over the system wide version, without replacing them.
Beware that some of the above fonts are (or will eventually be) available also in the variable fonts format — don't use it! Use instead the standard format where each font variation comes as an individual file, which is the format we've been using to ensure support across all platforms (and Dia, since this project requires an old Dia version which doesn't support variable fonts).
Some DIA source project files (but not all) have been renamed according to the following table — affecting the generated filenames too.
| original | renamed to |
|---|---|
developer-public.dia |
integration-manager-workflow.dia |
ff-nachher.dia |
ff-after.dia |
ff-vorher.dia |
ff-before.dia |
graph.dia |
commit-graph.dia |
graph-mit-refs.dia |
commit-graph-with-refs.dia |
merge-nachher.dia |
deleted (unused in original) |
objekte.dia |
git-objects.dia |
objekte-zusammenhang.dia |
git-objects-hierarchy.dia |
patches-per-mail.dia |
patches-via-email.dia |
pull_rebase.dia |
pull-rebase.dia |
rebase-nachher.dia |
rebase-after.dia |
rebase-onto-nachher.dia |
rebase-onto-after.dia |
rebase-onto-vorher.dia |
rebase-onto-before.dia |
rebase-vorher.dia |
rebase-before.dia |
svn_dcommit.dia |
svn-dcommit.dia |
svn_rebase.dia |
svn-rebase.dia |
struktur.dia |
repository-content.dia |
zentral.dia |
central-workflow.dia |
In order to make out the most from DIA, and produce good SVG image, we've resorted to some hackish workarounds.
When converting to SVG we use the Cairo SVG format (-t cairo-svg), a natively supported (but undocumented) alternative to Dia's default SVG format.
The Cairo SVG turned out to be more reliable than Dia's default SVG converter, for the latter was causing alignment-offset problems when text wrapped across multiple lines (a rather visible problem when dealing with centered-text in mono-spaced fonts).
Furthermore, SVG images generated via Cairo are not font dependent, for all text gets converted to SVG shapes, whereas the default SVG format relies on the specified font being present in the end-users' machine — lacking which it will fallback on some default system font replacement that would make the diagrams look ugly and break the intended proportions.
Font-dependency limits the choice of typefaces to those few safe fonts which are knows to be available on all OSs and devices (Times New Roman, Arial, Courier New, etc.), hence we decided to switch to the Cairo SVG format even though it required us to adopt Dia version 0.97-1, which is still not available on Dia's websites, and available only as pre-release for Windows.
Since AsciiDoc doesn't currently support images padding functionality, in order to ensure that the generated SVG images have some even padding around them across all output formats, I've added an invisible box in the bottom layer (i.e. no background drawn, and border line size 0).
The invisible box of each image has been carefully drawn to achieve the desired padding.
Some diagrams are part of a a series of images relating to a specific topic, often depicting the status of a Git object at different snapshots evolving in time. In order to preserve consistent proportions between these images, we add a same-width invisible background box (i.e. the one fitting the largest image of the group) to ensure that they will all scale proportionally when using percentages in the AsciiDoc source.
Similar images are gathered according to their group of belonging in the previews section below.
IMPORTANT — for correct diagrams preview, run
preview-generator.shand then openpreview.html.
- §6.2. » Fig.41
- §5.1. » Fig.30
- §5.2.2. » Fig.31
The following two images must have a same-width invisible background box to enforce consistent proportions, because they belong to a series of diagrams on the same topic:
- §2.2.6. » Fig.7
- §2.2.6.1. » Fig.8
- §3.1. » Fig.10
The following two images must have a same-width invisible background box to enforce consistent proportions, because they belong to a series of diagrams on the same topic:
- §3.3.2. » Fig.16
- §3.3.2. » Fig.17
- §2.2.3. » Fig.5
The following two images must have a same-width invisible background box to enforce consistent proportions, because they are similar diagrams on the same topic, even though they occur far apart.
- §2.2.2. » Fig.4
- §3.1.3. » Fig.12
- §11. » Fig.59
- §2.1.1. » Fig.1
- §5.6. » Fig.37
- §3.3.1 » Fig.15
- §5.10. » Fig.40
The following images must have a same-width invisible background box to enforce consistent proportions, because they belong to a series of similar diagrams on related topics, for both Git and SVN operations.
- §5.3.1. » Fig.33
- §5.3.2. » Fig.34
- §5.3.2. » Fig.35
- §5.4. » Fig.36
- §9.1.2.3. » Fig.56
- §9.1.2.3. » Fig.57
The following four images must have a same-width invisible background box to enforce consistent proportions, because they belong to a series of diagrams on the same topic:
- §4.1. » Fig.22
- §4.1. » Fig.23
- §4.1.7. » Fig.26
- §4.1.7. » Fig.27
- §3.1.1. » Fig.11
- §2.2.5. » Fig.6
- §2.2.1. » Fig.3
- Dia Diagram Editor — official website and dowloads.
- CSS Tricks » Using Custom Fonts With SVG in an Image Tag — by Thomas Yip.
- Vecta.io » Using Fonts in SVG — by Neel Singh.
Resources and articles on which fonts are safe to use based on common OSs' availability (this affects fonts used in SVG images too):
- CSS Font Stack — A complete collection of web safe CSS font stacks.
- MIT.edu » Safe web fonts — Article by Jacob Morzinski.
- Lifewire » Make Sure You're Using Web Safe Fonts — Article by Jennifer Kyrnin.