From 374672624537d2f18b5f8da95f7d1323a2d1b220 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 2 Jan 2024 05:03:29 +0100
Subject: [PATCH] docs: rework template and add stages framework

---
 docs/design/graphics.typ    | 79 +++++++++++++++++++++++++++++++++++++
 docs/design/iowo-design.typ | 31 +++++++++++++++
 docs/design/types.typ       | 16 --------
 docs/template.typ           | 47 +++++++++++++++++++---
 justfile                    |  1 +
 5 files changed, 152 insertions(+), 22 deletions(-)
 create mode 100644 docs/design/graphics.typ
 create mode 100644 docs/design/iowo-design.typ
 delete mode 100644 docs/design/types.typ

diff --git a/docs/design/graphics.typ b/docs/design/graphics.typ
new file mode 100644
index 0000000..cf5f7e0
--- /dev/null
+++ b/docs/design/graphics.typ
@@ -0,0 +1,79 @@
+#import "@preview/cetz:0.1.2"
+#import cetz.draw: *
+
+// quick reference
+// - `graphic` is for inline icons/images
+// - `canvas` is for centered more prominent stuff
+// - `group` can be used in either of ^, but not standalone
+
+#let graphic(what) = box({
+	cetz.canvas({
+		// any preamble-ish stuff can go here
+		set-style(
+			mark: (angle: 90deg)
+		)
+
+		what
+	})
+})
+
+#let canvas(what) = {
+	align(center, graphic(what))
+}
+
+
+// smaller stuff
+
+#let arrow(length: 1cm, lift: 4pt, stroke: 1pt) = graphic({
+	line((0, lift), (rel: (length, 0)), mark: (end: ">", stroke: stroke))
+
+	// hack for the bounding box bottom
+	// so that `lift` even has any effect
+	line((0, 0), (0, 0), stroke: none)
+})
+
+// larger stuff
+
+#let nodes(
+	distance: 3cm,
+	arrow-spacing: 0.15cm,
+	// cetz will support rounded rects in 0.2.0
+	style: (frame: "rect", padding: 0.1cm),
+	..labels,
+) = group({
+	let labels = labels.pos()
+
+	// draw each label itself
+	for (i, label) in labels.enumerate() {
+		if i != 0 {
+			set-origin((distance, 0))
+		}
+		content((0, 0), name: "label-" + str(i), label, ..style)
+	}
+
+	// then draw an arrow from each to each
+	// since an arrow is between two, the last one can't be connected with the "next-to-last" one
+	// so we leave it out
+	for i in range(labels.len() - 1) {
+		line(
+			(rel: (arrow-spacing, 0), to: "label-" + str(i) + ".right"),
+			(rel: (-arrow-spacing, 0), to: "label-" + str(i + 1) + ".left"),
+			mark: (end: ">"),
+		)
+	}
+})
+
+#let stages-overview = canvas({
+	nodes(
+		[Source],
+		[Graph IR],
+		[Optimizer],
+		[Compiler],
+		[VM Bytecode],
+		[VM],
+	)
+})
+
+// literally just for standalone display of the graphics alone
+#import "../template.typ": conf
+#show: conf
diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
new file mode 100644
index 0000000..5c02cee
--- /dev/null
+++ b/docs/design/iowo-design.typ
@@ -0,0 +1,31 @@
+#import "../template.typ": conf
+#import "graphics.typ"
+
+#show: conf.with(title: [iOwO design], subtitle: [don't worry, we're just dreaming])
+#show ">": graphics.arrow()
+
+= Type data model
+
+== Requirements
+
+- Color-aware
+	- It can handle colors and colorspaces for images
+	- ocio????
+- number/number type support
+- custom types (structs/enums)
+- algebraic enums
+- traits (`Numeric`...)
+
+= Execution stages
+
+#graphics.stages-overview
+
+== Source > Graph IR
+
+== Graph IR > VM Bytecode
+
+=== Optimizer
+
+=== Compiler
+
+== VM Bytecode > VM
diff --git a/docs/design/types.typ b/docs/design/types.typ
deleted file mode 100644
index 1fa9fac..0000000
--- a/docs/design/types.typ
+++ /dev/null
@@ -1,16 +0,0 @@
-#import "../template.typ": conf
-#show: doc => conf(
-	doc
-)
-
-= Type data model
-
-== Requirements
-
-- Color-aware
-	- It can handle colors and colorspaces for images
-	- ocio????
-- number/number type support
-- custom types (structs/enums)
-- algebraic enums
-- traits (`Numeric`...)
diff --git a/docs/template.typ b/docs/template.typ
index 6022b41..a688b07 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -1,12 +1,47 @@
+// would also be interesting to try out IBM Plex Mono/Sans sometime
+#let atk = "Atkinson Hyperlegible"
+#let fonts = (
+	main: (font: atk, size: 12pt),
+
+	title: (font: atk, size: 20pt),
+	subtitle: (font: atk, size: 10pt),
+	heading: (font: "Montserrat", weight: "regular"),
+)
+
 #let conf(
-	doc
+	title: none,
+	subtitle: none,
+	doc,
 ) = {
-	set text(font: "Atkinson Hyperlegible");
-	show heading: it => [
-		#set text(font: "Montserrat", weight: "regular")
+	set page(
+		numbering: "1 / 1",
+		header: locate(loc => {
+			datetime.today().display()
 
-		#it
-	]
+			if counter(page).at(loc).first() > 1 {
+				// on all pages other than the first, the title is useful to have at hand
+				h(1fr)
+				title
+			}
+		}),
+	)
+	set text(..fonts.main)
+	set heading(numbering: "A.1")
 
+	show heading: it => text(..fonts.heading, it)
+
+	// document title
+	if title != none {
+		align(
+			right,
+			text(..fonts.title, title)
+			+ v(-12pt)
+			+ text(..fonts.subtitle, subtitle)
+		)
+
+		v(0.25cm)
+	}
+
+	// content itself
 	doc
 }
diff --git a/justfile b/justfile
index a240f64..e0979b3 100644
--- a/justfile
+++ b/justfile
@@ -3,3 +3,4 @@ docs:
 		typst compile $doc --root=docs; \
 		mv "$(dirname $doc)/$(basename $doc .typ).pdf" docs/compiled/; \
 	done
+