68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
# Graphs
|
|
|
|
The `.dot` files carry **structure and meaning**. The palette lives in
|
|
`themes/*.gvpr` and is applied at render time.
|
|
|
|
```bash
|
|
./render.sh # every graph, every theme
|
|
./render.sh lucid # one theme
|
|
./render.sh dark system_overview
|
|
```
|
|
|
|
Needs graphviz (`sudo apt install graphviz`). The committed SVGs work without
|
|
it; this is only needed to re-render.
|
|
|
|
## Why themes, and why gvpr
|
|
|
|
The sources used to hardcode the dark palette inline, which meant one look and
|
|
no way to get another. `gvpr` rewrites the *parsed* graph, so it overrides
|
|
whatever a `.dot` set — one source renders in any theme without being edited.
|
|
|
|
Command-line `-G`/`-N`/`-E` flags would not do: those are defaults, and an
|
|
attribute written in the file beats them.
|
|
|
|
Colour is **baked into each SVG** rather than driven by CSS, because both docs
|
|
sites embed graphs with `<img src=...>`. That makes the SVG a separate document
|
|
the page's stylesheet cannot reach.
|
|
|
|
## Output
|
|
|
|
| Theme | Writes | For |
|
|
| --- | --- | --- |
|
|
| `dark` | `<name>.svg` | the docs site — this is the default, and what `docs/data/en/*.md` links to |
|
|
| `lucid` | `<name>.lucid.svg` | regulated documents, print, and sitting beside a real lucid.app export |
|
|
|
|
## Classes
|
|
|
|
Nodes, edges, clusters and the graph itself may carry a `class`. Anything
|
|
untagged gets the theme's neutral treatment.
|
|
|
|
| Class | Means | dark | lucid |
|
|
| --- | --- | --- | --- |
|
|
| `accent` | the emphasised thing | amber outline | blue outline, pale blue fill |
|
|
| `accent-text` | emphasised *label*, not a box | amber text | blue text |
|
|
| `ok` | live, working | green text | green outline, pale green fill |
|
|
| `artery` / `atlas` / `station` | belongs to that system | that system's colour | its pale equivalent |
|
|
| `muted` | present but not the point | grey text | grey fill |
|
|
|
|
`class` survives into the SVG (`<g class="node accent">`), so an **inlined** SVG
|
|
can also be styled by page CSS. That is not how the docs embed them, but it is
|
|
there if a page wants it.
|
|
|
|
## What themes never touch
|
|
|
|
- **`shape`** — a cylinder is a datastore, not a decoration.
|
|
- **`style=invis`** — layout scaffolding. Filling it would draw it.
|
|
- **`style=dashed`** — a weaker relationship; the theme preserves it and adds to it.
|
|
- **`label`, `rankdir`, `rank`, `fontsize`** — content and layout.
|
|
|
|
## Adding a theme
|
|
|
|
Drop a `themes/<name>.gvpr` in beside the others; `render.sh` picks it up with no
|
|
edit. Match the palette to `soleprint/common/theme/themes/<name>.css` so a
|
|
diagram and the page around it are the same visual language.
|
|
|
|
Name fonts that exist on the target. `lucid.gvpr` uses Arial deliberately: it is
|
|
on every Windows box and fontconfig aliases it to Liberation Sans on Linux, so
|
|
the SVG measures the same on both and text does not reflow out of its box.
|