A Khosra Demo

Readings from a rain gauge on a roof

Menu

Diagrams Written as Text

Contents

A fenced block in a diagram language is drawn rather than shown: the engine hands the source to the program that language belongs to, keeps the SVG it answers with, and the page shows the picture (khosra ADR-0391). Four languages, four programs, each optional — the host decides which are installed:

Fence Program Good at
```d2 D2 boxes and arrows laid out for you, with labels and containers
```dot Graphviz graphs: dependencies, state machines, anything with many edges
```pikchr Pikchr a line drawing placed by hand, the way pic placed them
```svgbob Svgbob ASCII art turned into clean lines — it reads well even undrawn

Each drawing is made once, when the site is rebuilt, and kept under /derived/ named by a hash of its source: an unchanged diagram is never drawn again, and no reader ever waits on a program. A fence the host cannot draw — the program is not installed, or it could not read the source — is shown as the code block it is, and khosra check says which and why.

D2

A post file is read into the index, which serves pages and feeds.
Where a post goes

Graphviz

From a file beside this page, with file= — the same option any fence takes, so one diagram can sit in several posts and stay one file:

The site root is indexed, every body is warmed, and a diagram fence goes to its program, whose SVG is kept under /derived/ once per hash before the swap.
What a rebuild does with a diagram

Pikchr

A fence goes into a program and an SVG comes out.
Fence in, picture out

Svgbob

Text written as ASCII art becomes an SVG with the same shape.

Placed

A drawing sits where a picture can, by the same words after the fence’s language — marginal, runaround-right, plate.

A box labelled gauge with an arrow to a box labelled log.
In the margin

marginal hangs a small drawing in the margin beside the paragraph it was written next to, the way a picture or a side note does. Below the width that has a margin it comes back into the column, small and centred. The words around it keep their own measure; the drawing does not push them aside.

A reading goes to the log, which feeds the chart.
Words run round it

runaround-right floats the drawing beside the text, the words running round it for as long as it lasts and then taking back the full width of the column. A drawing taller than the paragraph beside it keeps the next one running round it too, which is usually what a reader expects of a figure set into the text.

A reading goes from the gauge to the bottle, the ratio, the log, the chart and the page.
Wider than the column, with plate — a wide drawing at its own size

A drawing is never drawn larger than it was made: plate gives a wide one the room to be its own size, and leaves a small one as it is.

Not a diagram

Every other language is highlighted as code, exactly as before — a fence is drawn only when its language is one of the four above:

func main() { println("still code") }

khosra · khata 4d8d4c99 · content f6393d22 · 228 publications, 4256671 bytes · built in 1.460642387s