From efdfb5705ea10e269c9e4efdd44ea8ccf5dc3afc Mon Sep 17 00:00:00 2001
From: Schrottkatze <git@schrottkatze.de>
Date: Mon, 1 Jan 2024 23:56:31 +0100
Subject: [PATCH 01/26] actually write things

---
 docs/design/types.typ | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/design/types.typ b/docs/design/types.typ
index 2e4af6e..1fa9fac 100644
--- a/docs/design/types.typ
+++ b/docs/design/types.typ
@@ -3,8 +3,14 @@
 	doc
 )
 
-= meow nya
+= Type data model
 
-nyanyanya
+== Requirements
 
-#lorem(50)
+- Color-aware
+	- It can handle colors and colorspaces for images
+	- ocio????
+- number/number type support
+- custom types (structs/enums)
+- algebraic enums
+- traits (`Numeric`...)
-- 
2.46.0


From 388827a50eadbf800ed4532a1290d55d2d3d5e3e Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 2 Jan 2024 01:45:21 +0100
Subject: [PATCH 02/26] docs: add readme

---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..72f8952
--- /dev/null
+++ b/README.md
@@ -0,0 +1,16 @@
+# iOwO
+
+Tired of remembering if the argument order matters on this ImageMagick command?
+Tired of having shell parsing interfere with what you actually want to do?
+
+Fear no more, with iOwO (pronounced iowo (
+we believe at least (we don't know what we're doing [please help]!)
+)) you can just write a plain pipeline with [nushell]-ish syntax!
+Or that's what we want it to be at least.
+
+So, uh, grab a seat and a beverage, sit down, and maybe take a look around.
+Although there's not much here — _yet_.
+
+[please help]: ./CONTRIBUTING.md
+[nushell]: https://www.nushell.sh/
+
-- 
2.46.0


From 6217a984a24b02adedb2dd0316ff7da2b7e4cfc9 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 2 Jan 2024 02:45:20 +0100
Subject: [PATCH 03/26] repo: make typst compilation more generic

---
 docs/compiled/.gitkeep | 1 +
 justfile               | 7 +++++--
 2 files changed, 6 insertions(+), 2 deletions(-)
 create mode 100644 docs/compiled/.gitkeep

diff --git a/docs/compiled/.gitkeep b/docs/compiled/.gitkeep
new file mode 100644
index 0000000..a682a23
--- /dev/null
+++ b/docs/compiled/.gitkeep
@@ -0,0 +1 @@
+the just script will place compiled pdfs in here. thank you for your understanding.
diff --git a/justfile b/justfile
index 9228b4c..a240f64 100644
--- a/justfile
+++ b/justfile
@@ -1,2 +1,5 @@
-doc-design:
-	typst compile docs/design/*.typ --root=docs
+docs:
+	for doc in $(fd '.typ' './docs' --exclude 'template*' --exclude 'util*'); do \
+		typst compile $doc --root=docs; \
+		mv "$(dirname $doc)/$(basename $doc .typ).pdf" docs/compiled/; \
+	done
-- 
2.46.0


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 04/26] 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
+
-- 
2.46.0


From 32b547f9fae4588cf459136f1d51daeb15f80822 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Sun, 7 Jan 2024 21:43:26 +0100
Subject: [PATCH 05/26] meta: set up some signs

---
 CODE_OF_CONDUCT.md | 11 ++++++
 CONTRIBUTING.md    | 85 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 CONTRIBUTING.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..50eeec5
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,11 @@
+See https://www.rust-lang.org/policies/code-of-conduct.
+The current maintainers, that is,
+
+- [@Schrottkatze](https://forge.katzen.cafe/schrottkatze)
+- [@multisamplednight](https://forge.katzen.cafe/multisamplednight)
+- @iota-xSK
+
+are the entities to email, message or talk to if you feel like any interaction in the context of
+iOwO is not okay. We'll try to answer as soon as we can.
+
+Please do **not** open an issue. Notify the maintainers privately instead.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..461b274
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,85 @@
+# Contributing to iOwO
+
+Before we get started, thank you for thinking about doing so!
+
+## Through an issue
+
+- Be excellent to each other. Adhere to the [code of conduct].
+- About the title: If you had 5 seconds to tell someone the essence of the issue, what would it be?
+
+### Bugs
+
+- Write out in detail which steps in which order are necessary to reproduce the bug.
+- Include environmental information as well, in specific
+  - How did you install iOwO?
+  - What version of iOwO are you running?
+  - What operating system are you running?
+    In the case of a Linux distro, mention the specific distro and when you last update as well.
+- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump.
+
+### Feature requests
+
+- Be sure to include a motivation in which case your intended feature would be used,
+  even if it seems obvious to you.
+- Estimate what would be needed to implement the feature.
+  - Is it an addition to the language itself?
+  - Is it just a new command?
+  - Does it ground-breakingly change how iOwO works?
+
+## Through a PR
+
+1. Clone the repo.
+2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`.
+3. Implement your code changes with your favorite code editor.
+4. Try them with `cargo run`.
+5. If there are errors or warnings, go to step 3. Commit occasionally.
+6. Otherwise,
+  - if you have an account at https://forge.katzen.cafe,
+    1. fork the repo
+    2. set it up as a remote using `git remote add`
+    3. push using `git push @ -u`
+  - if you don't,
+    1. combine your patches using `git diff --patch` and throw them in a file
+    2. send that file to one of the maintainers per email
+      - alongside with a description of what it does
+
+### Tech stack
+
+The techstack we operate on is
+
+- [typst] for documents and concrete proposals
+- [Rust] for the actual code
+- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
+
+So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
+If you want to contribute thoughts and techincal designs, then consider taking a ride through
+[typst's excellent tutorial]!
+If you want to contribute art or the like, do that in whatever **you** are most comfortable with!
+
+[typst]: https://typst.app
+[Rust]: https://www.rust-lang.org
+[Inkscape]: https://inkscape.org/ 
+[GIMP]: https://www.gimp.org/
+[Blender]: https://www.blender.org/
+[The Rust Programming Language book]: https://doc.rust-lang.org/book/
+[typst's excellent tutorial]: https://typst.app/docs/tutorial
+
+## Politics
+
+- Current maintainers are defined as the entities listed in the [code of conduct].
+
+### PRs
+
+- Every PR requires an approving review from a maintainer (that is not the author) before merge.
+- Maintainers can merge their own PRs.
+  - But only after approval.
+
+### Major decisions
+
+- All current maintainers have to agree **unanimously**.
+- Agreement must be based on [informed consent].
+  - In effect, a maintainer has to understand what they agree to.
+
+[code of conduct]: ./CODE_OF_CONDUCT.md
+[informed consent]: https://en.wikipedia.org/wiki/Informed_consent
+
-- 
2.46.0


From b30cbb4d7bd46338d2223d7fa6cf3ef3bfc5e86c Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 9 Jan 2024 10:21:57 +0100
Subject: [PATCH 06/26] docs(design): actually write some content

---
 docs/design/graphics.typ    |   5 +-
 docs/design/iowo-design.typ | 198 ++++++++++++++++++++++++++++++++++--
 docs/template.typ           |  12 +++
 3 files changed, 204 insertions(+), 11 deletions(-)

diff --git a/docs/design/graphics.typ b/docs/design/graphics.typ
index cf5f7e0..5e0ef4c 100644
--- a/docs/design/graphics.typ
+++ b/docs/design/graphics.typ
@@ -67,10 +67,7 @@
 	nodes(
 		[Source],
 		[Graph IR],
-		[Optimizer],
-		[Compiler],
-		[VM Bytecode],
-		[VM],
+		[Runtime],
 	)
 })
 
diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index 5c02cee..4d8e8d8 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -2,15 +2,81 @@
 #import "graphics.typ"
 
 #show: conf.with(title: [iOwO design], subtitle: [don't worry, we're just dreaming])
-#show ">": graphics.arrow()
+
+// highlight important terms in bold
+#let expand(it) = {
+  ("("
+  + upper(it.first())
+  + "|"
+  + it.first()
+  + ")"
+  + it.clusters().slice(1).join()
+  + "s?")
+}
+#let singlify(it) = {
+  it = lower(it)
+  if it.ends-with("s") {
+    it = it.slice(0, -1)
+  }
+  it
+}
+#let terminate-recursion(it) = {
+  let clusters = it.text.clusters()
+  clusters.insert(1, "\u{FEFF}")
+  clusters.join()
+}
+// TODO: could make this just look over headings in section "Execution stages" tbh
+#let terms = (
+  "source",
+  "graph IR",
+  "runtime",
+
+  "optimizer",
+  "scheduler",
+  "VM",
+
+  "command",
+  "pipeline",
+  "input", "argument", "consumer",
+  "output", "streamer",
+  "modifier",
+)
+#let terms-trigger = regex(terms.map(expand).join("|"))
+#show raw: it => {
+  // avoid making terms in codeblocks bold
+  show terms-trigger: terminate-recursion
+  it
+}
+#show terms-trigger: strong
+
+// color codeblocks
+// haskell hl seems to work ok for this
+#show raw.where(lang: "iowo", block: true): it => {
+  raw(it.text, lang: "haskell", block: true)
+}
+
+// actual content lol
+
+#outline(
+  indent: auto,
+  fill: line(
+    length: 100%,
+    stroke: (
+      cap: "round",
+      join: "round",
+      thickness: 0.5pt,
+      paint: luma(75%),
+    ),
+  ),
+)
 
 = Type data model
 
 == Requirements
 
 - Color-aware
-	- It can handle colors and colorspaces for images
-	- ocio????
+  - It can handle colors and colorspaces for images
+  - OpenColorIO?
 - number/number type support
 - custom types (structs/enums)
 - algebraic enums
@@ -20,12 +86,130 @@
 
 #graphics.stages-overview
 
-== Source > Graph IR
+== Source
 
-== Graph IR > VM Bytecode
+Functional and pipeline-based.
+However, in contrast to classic shell commands,
+commands can have multiple outputs and multiple inputs.
+
+=== Commands
+
+The foundation of actually "doing" something.
+
+- Can have any, even infinite, amount of inputs and outputs.
+  - Their amounts may or may not be equal.
+- Inputs and outputs must have their types explicitly declared.
+- An command with
+  - at least one output is called a streamer.
+  - at least one input is called a consumer.
+  - _both_ at least one input and at least one output is _both_ a streamer and a consumer, and culminatively called a modifier.
+- May also contain spaces in its name.
+
+==== Inputs <input>
+
+- Based on position.
+- Inputs can be provided both through the pipeline and ad-hoc.
+- Ad-hoc inputs are called arguments.
+- So all of these are equivalent:
+
+```iowo
+1 | add 2
+add 1 2
+[ 1 2 ] | add
+```
+
+==== Outputs
+
+- Also based on position.
+
+=== Pipelines <pipeline>
+
+- Exchange data between streamers and consumers.
+
+==== Simple forwarding
+
+In the simplest case, where inputs map to outputs bijectively#footnote[one to one], pipelines are just pipes and forward unchanged:
+
+```iowo
+open owo.png | invert | save owo.png
+```
+
+==== Splitting <splitting>
+
+To handle each output of a streamer individually, they can be _split_:
+
+```iowo
+mask
+|> invert  -- would invert the unmasked part
+|> show    -- would show the masked part
+```
+
+==== Combination <combination>
+
+To throw multiple streamers into the inputs of a consumer, they can be _combined_:
+
+```iowo
+open base.png    >|
+open stencil.png >|
+mask
+```
+
+However, since lists are automatically spliced into inputs, this is equivalent to the above:
+
+```iowo
+[
+  open base.png,
+  open stencil.png,
+]
+| mask
+```
+
+=== Comments
+
+Done with any of `--` or `//`.
+
+=== Data types
+
+==== Lists
+
+- Signified by `[]` braces.
+- If thrown into a pipeline, it automatically works like a streamer.
+- Can be delimited by commas.
+  - Must be delimited by commas if a contained streamer takes an input.
+- May have a trailing comma.
+- Outputs of streamers are spliced into the contained list.
+  - In effect, they are automatically flattened.
+
+== Graph IR
 
 === Optimizer
 
-=== Compiler
+Merges and simplifies commands in the graph IR.
 
-== VM Bytecode > VM
+== Runtime
+
+=== Scheduler
+
+Looks at the graph IR and decides when the VM should execute what.
+
+=== VM <vm>
+
+= Open questions
+
+- @input
+  - At which position are arguments injected into command inputs?
+    - How could that be controlled if set to e.g. the end by default?
+    - Not all inputs are order-independent, e.g. `div`
+  - Should inputs and outputs really be positional?
+    - Could make more complex commands hard to read
+    - But keyworded could also make code very noisy
+    - Maybe a middle ground, such that at most 1 input is allowed to be positional?
+- @pipeline
+  - We need some way to reshuffle and reorder outputs and inputs in a pipeline
+- @splitting
+  - How would one split different outputs into a list?
+- Should outputs that are not thrown into a consumer be automatically displayed in some kind of debug view?
+  - Or should that be done instead using a debug `show` command or the like?
+- Should consumers be called sinks instead?
+  - Shorter
+  - More ambiguous if only looking at the first char though
diff --git a/docs/template.typ b/docs/template.typ
index a688b07..5bdf52a 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -15,6 +15,7 @@
 ) = {
 	set page(
 		numbering: "1 / 1",
+    margin: 3.25cm,
 		header: locate(loc => {
 			datetime.today().display()
 
@@ -29,6 +30,17 @@
 	set heading(numbering: "A.1")
 
 	show heading: it => text(..fonts.heading, it)
+  show raw.where(block: true): box.with(
+    fill: luma(95%),
+    inset: 1.25em,
+    radius: 0.75em,
+    width: 45em,
+  )
+  show raw.where(block: false): box.with(
+    fill: luma(95%),
+    outset: 0.25em,
+    radius: 0.25em,
+  )
 
 	// document title
 	if title != none {
-- 
2.46.0


From 9233b0e339203446778ea99266d4d9b5bd7af4cb Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 9 Jan 2024 10:27:07 +0100
Subject: [PATCH 07/26] docs(contributing): add penpot

---
 CONTRIBUTING.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 461b274..2931403 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -50,6 +50,7 @@ The techstack we operate on is
 - [typst] for documents and concrete proposals
 - [Rust] for the actual code
 - [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
+- [Penpot] for layouting prototypes and the like
 
 So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
 If you want to contribute thoughts and techincal designs, then consider taking a ride through
@@ -61,6 +62,7 @@ If you want to contribute art or the like, do that in whatever **you** are most
 [Inkscape]: https://inkscape.org/ 
 [GIMP]: https://www.gimp.org/
 [Blender]: https://www.blender.org/
+[Penpot]: https://penpot.app/
 [The Rust Programming Language book]: https://doc.rust-lang.org/book/
 [typst's excellent tutorial]: https://typst.app/docs/tutorial
 
-- 
2.46.0


From 6bd07b639bfa4a8e49562b08a4b288d0a5848d9d Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 9 Jan 2024 11:58:42 +0100
Subject: [PATCH 08/26] docs(design): add larger source example

---
 docs/design/graphics.typ    |  1 +
 docs/design/iowo-design.typ | 21 +++++++++++++++++++--
 docs/template.typ           |  3 ++-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/docs/design/graphics.typ b/docs/design/graphics.typ
index 5e0ef4c..320a46d 100644
--- a/docs/design/graphics.typ
+++ b/docs/design/graphics.typ
@@ -66,6 +66,7 @@
 #let stages-overview = canvas({
 	nodes(
 		[Source],
+    [AST],
 		[Graph IR],
 		[Runtime],
 	)
diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index 4d8e8d8..76b4697 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -25,9 +25,14 @@
   clusters.insert(1, "\u{FEFF}")
   clusters.join()
 }
-// TODO: could make this just look over headings in section "Execution stages" tbh
+// even though it looks like this could be automated with a `query`,
+// this'd require wrapping the whole document in a show rule
+// at which point `query` doesn't find anything anymore
 #let terms = (
   "source",
+  "ast",
+  "abstract syntax tree",
+  "Abstract Syntax Tree",
   "graph IR",
   "runtime",
 
@@ -86,7 +91,15 @@
 
 #graphics.stages-overview
 
-== Source
+== Source <source>
+
+```iowo
+open base.png    >|
+open stencil.png >|
+mask
+|> (invert | show)
+|> show
+```
 
 Functional and pipeline-based.
 However, in contrast to classic shell commands,
@@ -180,6 +193,10 @@ Done with any of `--` or `//`.
 - Outputs of streamers are spliced into the contained list.
   - In effect, they are automatically flattened.
 
+== Abstract Syntax Tree
+
+Essentially just the source lexed and parsed.
+
 == Graph IR
 
 === Optimizer
diff --git a/docs/template.typ b/docs/template.typ
index 5bdf52a..fc7f8b2 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -38,7 +38,8 @@
   )
   show raw.where(block: false): box.with(
     fill: luma(95%),
-    outset: 0.25em,
+    outset: (y: 0.25em),
+    inset: (x: 0.15em),
     radius: 0.25em,
   )
 
-- 
2.46.0


From b9ea83b1c6ff0c972c558a56c856e2a99707b573 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Tue, 9 Jan 2024 12:42:51 +0100
Subject: [PATCH 09/26] docs(design): get rid of ast

---
 docs/design/iowo-design.typ | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index 76b4697..ce8f5c5 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -31,8 +31,6 @@
 #let terms = (
   "source",
   "ast",
-  "abstract syntax tree",
-  "Abstract Syntax Tree",
   "graph IR",
   "runtime",
 
@@ -193,12 +191,12 @@ Done with any of `--` or `//`.
 - Outputs of streamers are spliced into the contained list.
   - In effect, they are automatically flattened.
 
-== Abstract Syntax Tree
-
-Essentially just the source lexed and parsed.
-
 == Graph IR
 
+The parsed representation of the source, and also what the runtime operates on.
+
+In a way, this is the AST, except that it's not a tree.
+
 === Optimizer
 
 Merges and simplifies commands in the graph IR.
-- 
2.46.0


From bebf2a97a44c7421ad0d8a68efc9d271fe525402 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:10:05 +0100
Subject: [PATCH 10/26] docs(design): add graph ir repr and explain a bit

---
 .gitignore                  |   1 +
 docs/design/graphics.typ    | 184 +++++++++++++++++++++++++++++++++++-
 docs/design/iowo-design.typ |  24 ++++-
 docs/template.typ           |   1 +
 4 files changed, 202 insertions(+), 8 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1407055..b2f817b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 /target
 .pre-commit-config.yaml
 *.pdf
+*.png
diff --git a/docs/design/graphics.typ b/docs/design/graphics.typ
index 320a46d..f14e65e 100644
--- a/docs/design/graphics.typ
+++ b/docs/design/graphics.typ
@@ -10,7 +10,8 @@
 	cetz.canvas({
 		// any preamble-ish stuff can go here
 		set-style(
-			mark: (angle: 90deg)
+			mark: (angle: 90deg),
+      stroke: (cap: "round", join: "round"),
 		)
 
 		what
@@ -24,7 +25,7 @@
 
 // smaller stuff
 
-#let arrow(length: 1cm, lift: 4pt, stroke: 1pt) = graphic({
+#let arrow(length: 0.4cm, lift: 3pt, stroke: 1pt) = graphic({
 	line((0, lift), (rel: (length, 0)), mark: (end: ">", stroke: stroke))
 
 	// hack for the bounding box bottom
@@ -34,7 +35,7 @@
 
 // larger stuff
 
-#let nodes(
+#let sequence(
 	distance: 3cm,
 	arrow-spacing: 0.15cm,
 	// cetz will support rounded rects in 0.2.0
@@ -64,14 +65,187 @@
 })
 
 #let stages-overview = canvas({
-	nodes(
+	sequence(
 		[Source],
-    [AST],
 		[Graph IR],
 		[Runtime],
 	)
 })
 
+// A few commands to help demonstration in the docs.
+// Supply a string to mark the input or output as simple.
+// (fwiw in typst, parenthesis around a single expression just evaluate the expression, and don't put it into an array)
+#let cmds = (
+  "const": (
+    inputs: (),
+    outputs: ("data",),
+  ),
+  "open": (
+    inputs: ("path",),
+    outputs: ("data",),
+  ),
+  "save": (
+    inputs: ("data", "path"),
+    outputs: (),
+  ),
+  "show": (
+    inputs: ("data",),
+    outputs: (),
+  ),
+  "invert": (
+    inputs: ("base",),
+    outputs: ("",),
+  ),
+  "mask": (
+    inputs: ("base", "stencil"),
+    outputs: ("masked", "rest"),
+  ),
+)
+
+#let opposite(anchor) = {
+  (
+    "bottom": "top",
+    "top": "bottom",
+  )
+  .at(anchor)
+}
+
+#let sockets(
+  start,
+  stop,
+  sockets,
+  socket-size: (0.5, 0.1),
+  socket-shape: "circle",
+  parent-name: "",
+  label-anchor: "bottom",
+) = {
+  for (i, socket) in sockets.enumerate() {
+    let x-ratio = (i + 1) / (sockets.len() + 1)
+    let center = (start, x-ratio, stop)
+
+    let socket-name = parent-name + "/" + socket
+
+    let common-args = (name: socket-name, fill: black)
+    if socket-shape == "rect" {
+      rect(
+        (rel: ((0, 0), -0.5, socket-size), to: center),
+        (rel: socket-size),
+        ..common-args,
+      )
+    } else if socket-shape == "circle" {
+      circle(
+        center,
+        radius: socket-size.at(1),
+        ..common-args,
+      )
+    } else {
+      panic("unknown socket shape: `" + socket-shape + "`")
+    }
+    set-style(fill: none)
+
+    // don't ask why, I don't know myself
+    let use-opposite-anchor = socket-shape == "circle"
+    content(
+      socket-name + "." + if use-opposite-anchor { opposite(label-anchor) } else { label-anchor },
+      anchor: opposite(label-anchor),
+      box(inset: 0.25em, text(8pt, socket)),
+    )
+  }
+}
+
+#let node(
+  at,
+  size: (3, 1.5),
+  ty: none,
+  body: none,
+  name: "unnamed",
+) = {
+  set-origin(at)
+  let label = [#ty]
+  if body != none {
+    label += [\ ] + text(0.7em, font: "IBM Plex Mono", body)
+    size.at(1) += 0.5
+  }
+  rect((0, 0), (rel: size), name: name)
+  content(((0, 0), 0.5, size), align(center, label))
+
+  // input and output sockets
+  if ty == none { return }
+  let ty = cmds.at(ty)
+
+  let sockets = sockets.with(parent-name: name)
+  sockets(
+    ((0, 0), "|-", size),
+    size,
+    ty.inputs,
+  )
+  sockets(
+    (0, 0),
+    ((0, 0), "-|", size),
+    label-anchor: "top",
+    ty.outputs,
+  )
+
+  // helper text
+  let helper(base, label, where) = {
+    if not type(base) != list or base.len() != 0 {
+      content(
+        name + "." + where + "-left",
+        anchor: "right",
+        box(inset: 0.25em, text(fill: luma(75%), label))
+      )
+    }
+  }
+
+  helper(ty.inputs, [in], "top")
+  helper(ty.outputs, [out], "bottom")
+
+  // reset the origin transform so other nodes can still work in the global coord system
+  // can't use groups since otherwise the anchors are not exported
+  set-origin(((0, 0), -1, at))
+}
+
+#let connect(from, to, bend: 1.5, mark-cfg: (size: 0.25, offset: 0.1)) = {
+  bezier(
+    from,
+    to,
+    (rel: (0, -bend * 1cm), to: from),
+    (rel: (0, bend * 1cm), to: to),
+  )
+  mark(
+    (rel: (0, mark-cfg.size + mark-cfg.offset), to: to),
+    (rel: (0, -mark-cfg.size)),
+    symbol: ">",
+  )
+}
+
+#let graph-example = canvas({
+  let x = 3
+  let y = -3
+  node((-x, -0.75 * y), ty: "const", body: "\"base.png\"", name: "base")
+  node((x, -0.75 * y), ty: "const", body: "\"stencil.png\"", name: "stencil")
+  node((-x, 0), ty: "open", name: "a")
+  node((x, 0), ty: "open", name: "b")
+  node((0, y), ty: "mask", name: "c")
+  node((-x, 2 * y), ty: "invert", name: "d")
+  node((-x, 2.75 * y), ty: "show", name: "e")
+  node((x, 2.75 * y), ty: "show", name: "f")
+
+  connect("base/data", "a/path")
+  connect("stencil/data", "b/path")
+
+  connect("a/data", "c/base")
+  connect("b/data", "c/stencil")
+
+  connect("c/masked", "d/base")
+  connect("d/", "e/data")
+
+  connect("c/rest", "f/data", bend: 2.5)
+})
+
 // literally just for standalone display of the graphics alone
 #import "../template.typ": conf
 #show: conf
+#set page(width: auto, height: auto)
+
+#graph-example
diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index ce8f5c5..e5f07f7 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -1,5 +1,6 @@
 #import "../template.typ": conf
 #import "graphics.typ"
+#import graphics: arrow
 
 #show: conf.with(title: [iOwO design], subtitle: [don't worry, we're just dreaming])
 
@@ -30,7 +31,7 @@
 // at which point `query` doesn't find anything anymore
 #let terms = (
   "source",
-  "ast",
+  "AST",
   "graph IR",
   "runtime",
 
@@ -85,18 +86,29 @@
 - algebraic enums
 - traits (`Numeric`...)
 
+#pagebreak()
+
 = Execution stages
 
 #graphics.stages-overview
 
+iOwO operates in stages. This has a number of benefits and implications:
+
+- One can just work on one aspect of the stages without having to know about the rest.
+- Bugs are easier to trace down to one stage.
+- Stages are also replacable, pluggable and usable somewhere else.
+  - For example, one could write a Just-In-Time compiler to replace the runtime stage, while preserving the source #arrow() graph IR step.
+
+However, this also makes the architecture somewhat more complicated. So here we try our best to describe how each stage looks like. If you have any feedback, feel free to drop it on #link("https://forge.katzen.cafe/katzen-cafe/iowo/issues")[the issues in the repository]!
+
 == Source <source>
 
 ```iowo
 open base.png    >|
 open stencil.png >|
 mask
+|> show12
 |> (invert | show)
-|> show
 ```
 
 Functional and pipeline-based.
@@ -151,8 +163,8 @@ To handle each output of a streamer individually, they can be _split_:
 
 ```iowo
 mask
-|> invert  -- would invert the unmasked part
 |> show    -- would show the masked part
+|> invert  -- would invert the unmasked part
 ```
 
 ==== Combination <combination>
@@ -193,16 +205,22 @@ Done with any of `--` or `//`.
 
 == Graph IR
 
+#graphics.graph-example
+
 The parsed representation of the source, and also what the runtime operates on.
 
 In a way, this is the AST, except that it's not a tree.
 
+It is represented in iOwO using adjacencies, where essentially the vertices#footnote[Nodes or commands in this case.] and their edges#footnote[Connections or pipes in this case.] are stored separately.
+
 === Optimizer
 
 Merges and simplifies commands in the graph IR.
 
 == Runtime
 
+Runs through all commands in the graph IR. It does not have any significantly other representation, and despite its name there's _no_ bytecode involved.
+
 === Scheduler
 
 Looks at the graph IR and decides when the VM should execute what.
diff --git a/docs/template.typ b/docs/template.typ
index fc7f8b2..899ab30 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -29,6 +29,7 @@
 	set text(..fonts.main)
 	set heading(numbering: "A.1")
 
+  show link: text.with(fill: blue)
 	show heading: it => text(..fonts.heading, it)
   show raw.where(block: true): box.with(
     fill: luma(95%),
-- 
2.46.0


From 221ca09961a8244745bc3eee1b48e338fa489867 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:22:29 +0100
Subject: [PATCH 11/26] docs: move config from design to template

---
 docs/design/iowo-design.typ | 75 ++-----------------------------------
 docs/template.typ           | 71 +++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 71 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index e5f07f7..9646ab8 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -2,76 +2,9 @@
 #import "graphics.typ"
 #import graphics: arrow
 
-#show: conf.with(title: [iOwO design], subtitle: [don't worry, we're just dreaming])
-
-// highlight important terms in bold
-#let expand(it) = {
-  ("("
-  + upper(it.first())
-  + "|"
-  + it.first()
-  + ")"
-  + it.clusters().slice(1).join()
-  + "s?")
-}
-#let singlify(it) = {
-  it = lower(it)
-  if it.ends-with("s") {
-    it = it.slice(0, -1)
-  }
-  it
-}
-#let terminate-recursion(it) = {
-  let clusters = it.text.clusters()
-  clusters.insert(1, "\u{FEFF}")
-  clusters.join()
-}
-// even though it looks like this could be automated with a `query`,
-// this'd require wrapping the whole document in a show rule
-// at which point `query` doesn't find anything anymore
-#let terms = (
-  "source",
-  "AST",
-  "graph IR",
-  "runtime",
-
-  "optimizer",
-  "scheduler",
-  "VM",
-
-  "command",
-  "pipeline",
-  "input", "argument", "consumer",
-  "output", "streamer",
-  "modifier",
-)
-#let terms-trigger = regex(terms.map(expand).join("|"))
-#show raw: it => {
-  // avoid making terms in codeblocks bold
-  show terms-trigger: terminate-recursion
-  it
-}
-#show terms-trigger: strong
-
-// color codeblocks
-// haskell hl seems to work ok for this
-#show raw.where(lang: "iowo", block: true): it => {
-  raw(it.text, lang: "haskell", block: true)
-}
-
-// actual content lol
-
-#outline(
-  indent: auto,
-  fill: line(
-    length: 100%,
-    stroke: (
-      cap: "round",
-      join: "round",
-      thickness: 0.5pt,
-      paint: luma(75%),
-    ),
-  ),
+#show: conf.with(
+  title: [iOwO design],
+  subtitle: [don't worry, we're just dreaming],
 )
 
 = Type data model
@@ -107,7 +40,7 @@ However, this also makes the architecture somewhat more complicated. So here we
 open base.png    >|
 open stencil.png >|
 mask
-|> show12
+|> show
 |> (invert | show)
 ```
 
diff --git a/docs/template.typ b/docs/template.typ
index 899ab30..23216db 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -8,6 +8,49 @@
 	heading: (font: "Montserrat", weight: "regular"),
 )
 
+#let expand(it) = {
+  ("("
+  + upper(it.first())
+  + "|"
+  + it.first()
+  + ")"
+  + it.clusters().slice(1).join()
+  + "s?")
+}
+#let singlify(it) = {
+  it = lower(it)
+  if it.ends-with("s") {
+    it = it.slice(0, -1)
+  }
+  it
+}
+#let terminate-recursion(it) = {
+  let clusters = it.text.clusters()
+  clusters.insert(1, "\u{FEFF}")
+  clusters.join()
+}
+// even though it looks like this could be automated with a `query`,
+// this'd require wrapping the whole document in a show rule
+// at which point `query` doesn't find anything anymore
+#let terms = (
+  "source",
+  "AST",
+  "graph IR",
+  "runtime",
+
+  "optimizer",
+  "scheduler",
+  "VM",
+
+  "command",
+  "pipeline",
+  "input", "argument", "consumer",
+  "output", "streamer",
+  "modifier",
+)
+// yes, the shadowing is intentional
+#let terms = regex(terms.map(expand).join("|"))
+
 #let conf(
 	title: none,
 	subtitle: none,
@@ -44,6 +87,20 @@
     radius: 0.25em,
   )
 
+  // highlight important terms in bold
+  show raw: it => {
+    // avoid making terms in codeblocks bold
+    show terms: terminate-recursion
+    it
+  }
+  show terms: strong
+
+  // color codeblocks
+  // haskell hl seems to work ok for this
+  show raw.where(lang: "iowo", block: true): it => {
+    raw(it.text, lang: "haskell", block: true)
+  }
+
 	// document title
 	if title != none {
 		align(
@@ -56,6 +113,20 @@
 		v(0.25cm)
 	}
 
+  // outline and other prelude info
+  outline(
+    indent: auto,
+    fill: line(
+      length: 100%,
+      stroke: (
+        cap: "round",
+        join: "round",
+        thickness: 0.5pt,
+        paint: luma(75%),
+      ),
+    ),
+  )
+
 	// content itself
 	doc
 }
-- 
2.46.0


From cbbe2c325384ddd517b848398fdbde86231366f7 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:28:01 +0100
Subject: [PATCH 12/26] docs: only highlight standalone terms

---
 docs/template.typ | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/template.typ b/docs/template.typ
index 23216db..712c6e7 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -48,8 +48,8 @@
   "output", "streamer",
   "modifier",
 )
-// yes, the shadowing is intentional
-#let terms = regex(terms.map(expand).join("|"))
+// yes, the shadowing is intentional to avoid accidentally using the list
+#let terms = regex("\\b(" + terms.map(expand).join("|") + ")\\b")
 
 #let conf(
 	title: none,
-- 
2.46.0


From 35695537bdd8ac5f73c41caff943b18f84c3ec69 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:34:52 +0100
Subject: [PATCH 13/26] docs(design): rename command -> instruction

---
 docs/design/iowo-design.typ | 18 +++++++++---------
 docs/template.typ           |  2 +-
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index 9646ab8..fc0069d 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -46,16 +46,16 @@ mask
 
 Functional and pipeline-based.
 However, in contrast to classic shell commands,
-commands can have multiple outputs and multiple inputs.
+instructions can have multiple outputs and multiple inputs.
 
-=== Commands
+=== Instructions
 
 The foundation of actually "doing" something.
 
 - Can have any, even infinite, amount of inputs and outputs.
   - Their amounts may or may not be equal.
 - Inputs and outputs must have their types explicitly declared.
-- An command with
+- An instruction with
   - at least one output is called a streamer.
   - at least one input is called a consumer.
   - _both_ at least one input and at least one output is _both_ a streamer and a consumer, and culminatively called a modifier.
@@ -144,15 +144,15 @@ The parsed representation of the source, and also what the runtime operates on.
 
 In a way, this is the AST, except that it's not a tree.
 
-It is represented in iOwO using adjacencies, where essentially the vertices#footnote[Nodes or commands in this case.] and their edges#footnote[Connections or pipes in this case.] are stored separately.
+It is represented in iOwO using adjacencies, where essentially the vertices#footnote[Nodes or instructions in this case.] and their edges#footnote[Connections or pipes in this case.] are stored separately.
 
 === Optimizer
 
-Merges and simplifies commands in the graph IR.
+Merges and simplifies instructions in the graph IR.
 
 == Runtime
 
-Runs through all commands in the graph IR. It does not have any significantly other representation, and despite its name there's _no_ bytecode involved.
+Runs through all instructions in the graph IR. It does not have any significantly other representation, and despite its name there's _no_ bytecode involved.
 
 === Scheduler
 
@@ -163,11 +163,11 @@ Looks at the graph IR and decides when the VM should execute what.
 = Open questions
 
 - @input
-  - At which position are arguments injected into command inputs?
+  - At which position are arguments injected into instruction inputs?
     - How could that be controlled if set to e.g. the end by default?
     - Not all inputs are order-independent, e.g. `div`
   - Should inputs and outputs really be positional?
-    - Could make more complex commands hard to read
+    - Could make more complex instructions hard to read
     - But keyworded could also make code very noisy
     - Maybe a middle ground, such that at most 1 input is allowed to be positional?
 - @pipeline
@@ -175,7 +175,7 @@ Looks at the graph IR and decides when the VM should execute what.
 - @splitting
   - How would one split different outputs into a list?
 - Should outputs that are not thrown into a consumer be automatically displayed in some kind of debug view?
-  - Or should that be done instead using a debug `show` command or the like?
+  - Or should that be done instead using a debug `show` instruction or the like?
 - Should consumers be called sinks instead?
   - Shorter
   - More ambiguous if only looking at the first char though
diff --git a/docs/template.typ b/docs/template.typ
index 712c6e7..8059e5c 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -42,7 +42,7 @@
   "scheduler",
   "VM",
 
-  "command",
+  "instruction",
   "pipeline",
   "input", "argument", "consumer",
   "output", "streamer",
-- 
2.46.0


From fe96a17551e52c7a7865bb901d81aad3646fd1f7 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:39:21 +0100
Subject: [PATCH 14/26] docs: justify main text

---
 docs/template.typ | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/template.typ b/docs/template.typ
index 8059e5c..602d96a 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -69,6 +69,7 @@
 			}
 		}),
 	)
+  set par(justify: true)
 	set text(..fonts.main)
 	set heading(numbering: "A.1")
 
@@ -86,6 +87,11 @@
     inset: (x: 0.15em),
     radius: 0.25em,
   )
+  show raw.where(block: true): it => {
+    // don't try to put codeblocks into blocktext
+    set par(justify: false)
+    it
+  }
 
   // highlight important terms in bold
   show raw: it => {
-- 
2.46.0


From ef7ab3e2390d601428d1f368d75411e3f2e498f0 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:42:52 +0100
Subject: [PATCH 15/26] docs(design): explain individual lines of input ex

---
 docs/design/iowo-design.typ | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index fc0069d..ad1849d 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -69,9 +69,9 @@ The foundation of actually "doing" something.
 - So all of these are equivalent:
 
 ```iowo
-1 | add 2
-add 1 2
-[ 1 2 ] | add
+add 1 2        -- all inputs as arguments
+[ 1 2 ] | add  -- all inputs through the pipeline
+1 | add 2      -- one input through the pipeline, one as argument
 ```
 
 ==== Outputs
-- 
2.46.0


From 5f95f36214e6ce406539a5a59295473f4fe96780 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:54:29 +0100
Subject: [PATCH 16/26] docs: place strategic pagebreaks automatically

---
 docs/design/iowo-design.typ |  2 --
 docs/template.typ           | 14 +++++++++++++-
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index ad1849d..f8b4316 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -19,8 +19,6 @@
 - algebraic enums
 - traits (`Numeric`...)
 
-#pagebreak()
-
 = Execution stages
 
 #graphics.stages-overview
diff --git a/docs/template.typ b/docs/template.typ
index 602d96a..3077478 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -73,8 +73,10 @@
 	set text(..fonts.main)
 	set heading(numbering: "A.1")
 
-  show link: text.with(fill: blue)
 	show heading: it => text(..fonts.heading, it)
+  // color links
+  show link: text.with(fill: blue)
+  // prettify codeblocks
   show raw.where(block: true): box.with(
     fill: luma(95%),
     inset: 1.25em,
@@ -93,6 +95,16 @@
     it
   }
 
+  // semi-strategically place pagebreaks for better orientation
+  let pagebreak-before(it) = pagebreak() + it
+  show heading.where(outlined: true): it => {
+    if it.level <= 2 {
+      pagebreak()
+    }
+
+    it
+  }
+
   // highlight important terms in bold
   show raw: it => {
     // avoid making terms in codeblocks bold
-- 
2.46.0


From 9a2f982d40e62f41422c4e0f15babe49e5d28d5c Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 21:58:51 +0100
Subject: [PATCH 17/26] docs: use weak pagebreaks for automatic pagebreaks

---
 docs/template.typ | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/template.typ b/docs/template.typ
index 3077478..a212e48 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -99,7 +99,7 @@
   let pagebreak-before(it) = pagebreak() + it
   show heading.where(outlined: true): it => {
     if it.level <= 2 {
-      pagebreak()
+      pagebreak(weak: true)
     }
 
     it
-- 
2.46.0


From 47f602596304c9e6a1874d73cbda4bfdd5e4f99f Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 23:21:33 +0100
Subject: [PATCH 18/26] repo: switch to nu for just

---
 docs/design/iowo-design.typ         |  2 +-
 docs/design/{ => util}/graphics.typ |  2 +-
 flake.lock                          | 38 ++++++++++++++---------------
 flake.nix                           |  4 +--
 justfile                            | 14 +++++++----
 5 files changed, 32 insertions(+), 28 deletions(-)
 rename docs/design/{ => util}/graphics.typ (99%)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index f8b4316..1feb7d0 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -1,5 +1,5 @@
 #import "../template.typ": conf
-#import "graphics.typ"
+#import "util/graphics.typ"
 #import graphics: arrow
 
 #show: conf.with(
diff --git a/docs/design/graphics.typ b/docs/design/util/graphics.typ
similarity index 99%
rename from docs/design/graphics.typ
rename to docs/design/util/graphics.typ
index f14e65e..f097b51 100644
--- a/docs/design/graphics.typ
+++ b/docs/design/util/graphics.typ
@@ -244,7 +244,7 @@
 })
 
 // literally just for standalone display of the graphics alone
-#import "../template.typ": conf
+#import "../../template.typ": conf
 #show: conf
 #set page(width: auto, height: auto)
 
diff --git a/flake.lock b/flake.lock
index 0ee4e36..fd2920d 100644
--- a/flake.lock
+++ b/flake.lock
@@ -8,11 +8,11 @@
         "pre-commit-hooks": "pre-commit-hooks"
       },
       "locked": {
-        "lastModified": 1699541523,
-        "narHash": "sha256-Rv0ryuBC5KtA/3YqwIEe58Tabu71qSGnGcGRd67mMUY=",
+        "lastModified": 1704835383,
+        "narHash": "sha256-SoC0rYR9iHW0dVOEmxNEfa8vk9dTK86P5iXTgHafmwM=",
         "owner": "cachix",
         "repo": "devenv",
-        "rev": "14fdefc0bb80c3d6f3a18a491e33429b4064c371",
+        "rev": "18ef9849d1ecac7a9a7920eb4f2e4adcf67a8c3a",
         "type": "github"
       },
       "original": {
@@ -27,11 +27,11 @@
         "rust-analyzer-src": "rust-analyzer-src"
       },
       "locked": {
-        "lastModified": 1699510895,
-        "narHash": "sha256-eaOkJUvHeYNW/xEoRotz0rHkKihKoQdWB1ctX4q1MTQ=",
+        "lastModified": 1704867811,
+        "narHash": "sha256-pG4O1vPpNSMjz7p/5x+/OH4tXC0thzAPbJ55kI/W5dU=",
         "owner": "nix-community",
         "repo": "fenix",
-        "rev": "8eeef23f2c8d092227af40eff98afe5b41891e3b",
+        "rev": "93e89638c15512db65e931f26ce36edf8cfbb4a5",
         "type": "github"
       },
       "original": {
@@ -186,11 +186,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1699099776,
-        "narHash": "sha256-X09iKJ27mGsGambGfkKzqvw5esP1L/Rf8H3u3fCqIiU=",
+        "lastModified": 1704538339,
+        "narHash": "sha256-1734d3mQuux9ySvwf6axRWZRBhtcZA9Q8eftD6EZg6U=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "85f1ba3e51676fa8cc604a3d863d729026a6b8eb",
+        "rev": "46ae0210ce163b3cba6c7da08840c1d63de9c701",
         "type": "github"
       },
       "original": {
@@ -202,16 +202,16 @@
     },
     "nixpkgs_3": {
       "locked": {
-        "lastModified": 1699291058,
-        "narHash": "sha256-5ggduoaAMPHUy4riL+OrlAZE14Kh7JWX4oLEs22ZqfU=",
+        "lastModified": 1704722960,
+        "narHash": "sha256-mKGJ3sPsT6//s+Knglai5YflJUF2DGj7Ai6Ynopz0kI=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "41de143fda10e33be0f47eab2bfe08a50f234267",
+        "rev": "317484b1ead87b9c1b8ac5261a8d2dd748a0492d",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-23.05",
+        "ref": "nixos-unstable",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -231,11 +231,11 @@
         "nixpkgs-stable": "nixpkgs-stable"
       },
       "locked": {
-        "lastModified": 1688056373,
-        "narHash": "sha256-2+SDlNRTKsgo3LBRiMUcoEUb6sDViRNQhzJquZ4koOI=",
+        "lastModified": 1704725188,
+        "narHash": "sha256-qq8NbkhRZF1vVYQFt1s8Mbgo8knj+83+QlL5LBnYGpI=",
         "owner": "cachix",
         "repo": "pre-commit-hooks.nix",
-        "rev": "5843cf069272d92b60c3ed9e55b7a8989c01d4c7",
+        "rev": "ea96f0c05924341c551a797aaba8126334c505d2",
         "type": "github"
       },
       "original": {
@@ -255,11 +255,11 @@
     "rust-analyzer-src": {
       "flake": false,
       "locked": {
-        "lastModified": 1699451299,
-        "narHash": "sha256-7HJMyp62fCS6/aCCCASz8MdJM2/M8d1pBNukyLmPdwA=",
+        "lastModified": 1704833483,
+        "narHash": "sha256-Ox01mpYmjapNYaqOu4fMS/4Ma9NLd2rVNz6d4rJmcf4=",
         "owner": "rust-lang",
         "repo": "rust-analyzer",
-        "rev": "7059ae2fc2d55fa20d7e2671597b516431129445",
+        "rev": "ae6e73772432cfe35bb0ff6de6fdcfa908642b67",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index c8148c6..ab394bf 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,6 +1,6 @@
 {
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     systems.url = "github:nix-systems/default";
     devenv.url = "github:cachix/devenv";
     fenix.url = "github:nix-community/fenix";
@@ -36,7 +36,7 @@
                     rustfmt.enable = true;
                   };
                 
-                  packages = [];
+                  packages = with pkgs; [just nushell typst];
                 })
               ];
             };
diff --git a/justfile b/justfile
index e0979b3..7870440 100644
--- a/justfile
+++ b/justfile
@@ -1,6 +1,10 @@
 docs:
-	for doc in $(fd '.typ' './docs' --exclude 'template*' --exclude 'util*'); do \
-		typst compile $doc --root=docs; \
-		mv "$(dirname $doc)/$(basename $doc .typ).pdf" docs/compiled/; \
-	done
-
+  #!/usr/bin/env nu
+  glob **/*.typ --exclude [**/{template.typ,util/**}] | par-each { |source|
+    typst compile $source --root=docs
+    let pdf = (
+      (echo $source | path dirname)
+      | path join (echo $source | path basename | str replace ".typ" ".pdf")
+    )
+    mv $pdf docs/compiled
+  } | ignore
-- 
2.46.0


From a9b69094cc3055d5a9d15f0854542cebeeb12c51 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 23:31:21 +0100
Subject: [PATCH 19/26] repo: expand on CONTRIBUTING.md about PRs

---
 CONTRIBUTING.md | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2931403..9c72e6d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -82,6 +82,33 @@ If you want to contribute art or the like, do that in whatever **you** are most
 - Agreement must be based on [informed consent].
   - In effect, a maintainer has to understand what they agree to.
 
+# Interacting with PRs
+
+> [!NOTE] Remember, be respectful.
+> Entities invest their free time and motivation into making these changes,
+> treat them appropiately.
+
+- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
+- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets).
+
+## Initial steps for a new contributor or new local checkout
+
+```sh
+git remote add <contributor-name> https://forge.katzen.cafe/<contributor-account>/iowo.git
+git remote update <contributor-name>
+```
+
+## After setting up the remote
+
+- You can repeat this step anytime you want to switch branches or update your local checkout.
+- The PR branch is visible just below the PR title on forgejo, after the colon (`:`).
+
+```sh
+git switch <pr-branch>
+git pull
+```
+
+
 [code of conduct]: ./CODE_OF_CONDUCT.md
 [informed consent]: https://en.wikipedia.org/wiki/Informed_consent
-
+[git's remotes]: https://git-scm.com/docs/git-remote
-- 
2.46.0


From 41e21bac1684c7ff5831f02bcf532352c8ddb666 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Wed, 10 Jan 2024 23:35:39 +0100
Subject: [PATCH 20/26] repo: add helpful comment to justfile

---
 justfile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/justfile b/justfile
index 7870440..3715e45 100644
--- a/justfile
+++ b/justfile
@@ -1,3 +1,4 @@
+# Compile all documentation as in proposals and design documents, placing them under `docs/compiled`.
 docs:
   #!/usr/bin/env nu
   glob **/*.typ --exclude [**/{template.typ,util/**}] | par-each { |source|
-- 
2.46.0


From e986f0fc1df34f45cd184b3b95bf16b2d5b9369e Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Thu, 11 Jan 2024 11:51:03 +0100
Subject: [PATCH 21/26] docs(design): split into function and instruction

---
 docs/design/iowo-design.typ | 55 +++++++++++++++++++++++++------------
 docs/template.typ           |  2 ++
 2 files changed, 40 insertions(+), 17 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index 1feb7d0..a2f3c5e 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -23,12 +23,15 @@
 
 #graphics.stages-overview
 
-iOwO operates in stages. This has a number of benefits and implications:
+iOwO operates in stages.
+This has a number of benefits and implications:
 
 - One can just work on one aspect of the stages without having to know about the rest.
 - Bugs are easier to trace down to one stage.
 - Stages are also replacable, pluggable and usable somewhere else.
-  - For example, one could write a Just-In-Time compiler to replace the runtime stage, while preserving the source #arrow() graph IR step.
+  - For example,
+    one could write a Just-In-Time compiler as a new executor to replace the runtime stage,
+    while preserving the source #arrow() graph IR step.
 
 However, this also makes the architecture somewhat more complicated. So here we try our best to describe how each stage looks like. If you have any feedback, feel free to drop it on #link("https://forge.katzen.cafe/katzen-cafe/iowo/issues")[the issues in the repository]!
 
@@ -44,19 +47,22 @@ mask
 
 Functional and pipeline-based.
 However, in contrast to classic shell commands,
-instructions can have multiple outputs and multiple inputs.
+functions can have multiple outputs and multiple inputs.
 
-=== Instructions
+=== Functions
+
+`open`, `invert`, `mask`, `show` and friends.
 
 The foundation of actually "doing" something.
 
 - Can have any, even infinite, amount of inputs and outputs.
   - Their amounts may or may not be equal.
 - Inputs and outputs must have their types explicitly declared.
-- An instruction with
+- An function with
   - at least one output is called a streamer.
   - at least one input is called a consumer.
-  - _both_ at least one input and at least one output is _both_ a streamer and a consumer, and culminatively called a modifier.
+  - _both_ at least one input and at least one output is _both_ a streamer and a consumer,
+    and culminatively called a modifier.
 - May also contain spaces in its name.
 
 ==== Inputs <input>
@@ -82,7 +88,9 @@ add 1 2        -- all inputs as arguments
 
 ==== Simple forwarding
 
-In the simplest case, where inputs map to outputs bijectively#footnote[one to one], pipelines are just pipes and forward unchanged:
+In the simplest case,
+where inputs map to outputs bijectively#footnote[one to one],
+pipelines are just pipes and forward unchanged:
 
 ```iowo
 open owo.png | invert | save owo.png
@@ -100,7 +108,8 @@ mask
 
 ==== Combination <combination>
 
-To throw multiple streamers into the inputs of a consumer, they can be _combined_:
+To throw multiple streamers into the inputs of a consumer,
+they can be _combined_:
 
 ```iowo
 open base.png    >|
@@ -108,7 +117,8 @@ open stencil.png >|
 mask
 ```
 
-However, since lists are automatically spliced into inputs, this is equivalent to the above:
+However, since lists are automatically spliced into inputs,
+this is equivalent to the above:
 
 ```iowo
 [
@@ -142,15 +152,23 @@ The parsed representation of the source, and also what the runtime operates on.
 
 In a way, this is the AST, except that it's not a tree.
 
-It is represented in iOwO using adjacencies, where essentially the vertices#footnote[Nodes or instructions in this case.] and their edges#footnote[Connections or pipes in this case.] are stored separately.
+It is represented in iOwO using adjacencies, where essentially
+the vertices#footnote[Nodes or functions in this case.]
+and their edges#footnote[Connections or pipes in this case.]
+are stored separately.
 
 === Optimizer
 
-Merges and simplifies instructions in the graph IR.
+Merges and simplifies functions in the graph IR.
 
-== Runtime
+== Runtime <runtime>
 
-Runs through all instructions in the graph IR. It does not have any significantly other representation, and despite its name there's _no_ bytecode involved.
+Runs through all functions in the graph IR.
+It does not have any significantly other representation,
+and despite its name there's _no_ bytecode involved.
+
+Different runtimes are called executors.
+Executors operate on instructions instead of functions.
 
 === Scheduler
 
@@ -161,19 +179,22 @@ Looks at the graph IR and decides when the VM should execute what.
 = Open questions
 
 - @input
-  - At which position are arguments injected into instruction inputs?
+  - At which position are arguments injected into function inputs?
     - How could that be controlled if set to e.g. the end by default?
     - Not all inputs are order-independent, e.g. `div`
   - Should inputs and outputs really be positional?
-    - Could make more complex instructions hard to read
+    - Could make more complex functions hard to read
     - But keyworded could also make code very noisy
     - Maybe a middle ground, such that at most 1 input is allowed to be positional?
 - @pipeline
   - We need some way to reshuffle and reorder outputs and inputs in a pipeline
 - @splitting
   - How would one split different outputs into a list?
-- Should outputs that are not thrown into a consumer be automatically displayed in some kind of debug view?
-  - Or should that be done instead using a debug `show` instruction or the like?
+- @runtime
+  - What is the difference between an instruction and a function?
+- Should outputs that are not thrown into a consumer
+  be automatically displayed in some kind of debug view?
+  - Or should that be done instead using a debug `show` function or the like?
 - Should consumers be called sinks instead?
   - Shorter
   - More ambiguous if only looking at the first char though
diff --git a/docs/template.typ b/docs/template.typ
index a212e48..9f48dba 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -37,11 +37,13 @@
   "AST",
   "graph IR",
   "runtime",
+  "executor",
 
   "optimizer",
   "scheduler",
   "VM",
 
+  "function",
   "instruction",
   "pipeline",
   "input", "argument", "consumer",
-- 
2.46.0


From ec3d1310bf25ebdcb65b2e28c50e743e6cf7da66 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Thu, 18 Jan 2024 22:38:19 +0100
Subject: [PATCH 22/26] docs: apply most review

---
 .envrc                      |  3 ++-
 CODE_OF_CONDUCT.md          |  1 -
 CONTRIBUTING.md             | 54 +++++++++++++++++++------------------
 docs/design/iowo-design.typ | 14 +---------
 4 files changed, 31 insertions(+), 41 deletions(-)

diff --git a/.envrc b/.envrc
index ff5954f..30f4045 100644
--- a/.envrc
+++ b/.envrc
@@ -1 +1,2 @@
-use flake . --impure
\ No newline at end of file
+use flake . --impure
+export TYPST_ROOT="$(pwd)/docs"
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 50eeec5..b9a53c0 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -3,7 +3,6 @@ The current maintainers, that is,
 
 - [@Schrottkatze](https://forge.katzen.cafe/schrottkatze)
 - [@multisamplednight](https://forge.katzen.cafe/multisamplednight)
-- @iota-xSK
 
 are the entities to email, message or talk to if you feel like any interaction in the context of
 iOwO is not okay. We'll try to answer as soon as we can.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9c72e6d..d6000ff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,35 +4,35 @@ Before we get started, thank you for thinking about doing so!
 
 ## Through an issue
 
-- Be excellent to each other. Adhere to the [code of conduct].
+- Be excellent to each other. Adhere to the [code of conduct]
 - About the title: If you had 5 seconds to tell someone the essence of the issue, what would it be?
 
 ### Bugs
 
-- Write out in detail which steps in which order are necessary to reproduce the bug.
+- Write out in detail which steps in which order are necessary to reproduce the bug
 - Include environmental information as well, in specific
   - How did you install iOwO?
   - What version of iOwO are you running?
   - What operating system are you running?
-    In the case of a Linux distro, mention the specific distro and when you last update as well.
-- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump.
+    In the case of a Linux distro, mention the specific distro and when you last update as well
+- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump
 
 ### Feature requests
 
-- Be sure to include a motivation in which case your intended feature would be used,
-  even if it seems obvious to you.
-- Estimate what would be needed to implement the feature.
+- Be sure to include a motivation in which case your intended feature would be used
+  even if it seems obvious to you
+- Estimate what would be needed to implement the feature
   - Is it an addition to the language itself?
   - Is it just a new command?
   - Does it ground-breakingly change how iOwO works?
 
 ## Through a PR
 
-1. Clone the repo.
-2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`.
-3. Implement your code changes with your favorite code editor.
-4. Try them with `cargo run`.
-5. If there are errors or warnings, go to step 3. Commit occasionally.
+1. Clone the repo
+2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`
+3. Implement your code changes with your favorite code editor
+4. Try them with `cargo run`
+5. If there are errors or warnings, go to step 3. Commit occasionally
 6. Otherwise,
   - if you have an account at https://forge.katzen.cafe,
     1. fork the repo
@@ -42,6 +42,8 @@ Before we get started, thank you for thinking about doing so!
     1. combine your patches using `git diff --patch` and throw them in a file
     2. send that file to one of the maintainers per email
       - alongside with a description of what it does
+    3. also mention in the mail that we should consider GitHub and GitLab mirrors,
+       referring to this line
 
 ### Tech stack
 
@@ -68,28 +70,28 @@ If you want to contribute art or the like, do that in whatever **you** are most
 
 ## Politics
 
-- Current maintainers are defined as the entities listed in the [code of conduct].
+- Current maintainers are defined as the entities listed in the [code of conduct]
 
 ### PRs
 
-- Every PR requires an approving review from a maintainer (that is not the author) before merge.
-- Maintainers can merge their own PRs.
-  - But only after approval.
+- Every PR requires an approving review from a maintainer (that is not the author) before merge
+- Maintainers can merge their own PRs
+  - But only after approval
 
 ### Major decisions
 
-- All current maintainers have to agree **unanimously**.
-- Agreement must be based on [informed consent].
-  - In effect, a maintainer has to understand what they agree to.
+- All current maintainers have to agree **unanimously**
+- Agreement must be based on [informed consent]
+  - In effect, a maintainer has to understand what they agree to
 
 # Interacting with PRs
 
-> [!NOTE] Remember, be respectful.
-> Entities invest their free time and motivation into making these changes,
-> treat them appropiately.
+Remember, be respectful.
+Entities invest their free time and motivation into making these changes,
+treat them appropiately.
 
-- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
-- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets).
+- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good
+- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets)
 
 ## Initial steps for a new contributor or new local checkout
 
@@ -100,8 +102,8 @@ git remote update <contributor-name>
 
 ## After setting up the remote
 
-- You can repeat this step anytime you want to switch branches or update your local checkout.
-- The PR branch is visible just below the PR title on forgejo, after the colon (`:`).
+- You can repeat this step anytime you want to switch branches or update your local checkout
+- The PR branch is visible just below the PR title on Forgejo, after the colon (`:`)
 
 ```sh
 git switch <pr-branch>
diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index a2f3c5e..aa9f9f2 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -7,19 +7,7 @@
   subtitle: [don't worry, we're just dreaming],
 )
 
-= Type data model
-
-== Requirements
-
-- Color-aware
-  - It can handle colors and colorspaces for images
-  - OpenColorIO?
-- number/number type support
-- custom types (structs/enums)
-- algebraic enums
-- traits (`Numeric`...)
-
-= Execution stages
+= Evaluation stages
 
 #graphics.stages-overview
 
-- 
2.46.0


From 53cc3f26ddb35d927e6ba7778df6180d60a94ca3 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Fri, 19 Jan 2024 03:09:31 +0100
Subject: [PATCH 23/26] docs: bring back punctuation at end of points

---
 CONTRIBUTING.md | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d6000ff..f81c296 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,35 +4,35 @@ Before we get started, thank you for thinking about doing so!
 
 ## Through an issue
 
-- Be excellent to each other. Adhere to the [code of conduct]
+- Be excellent to each other. Adhere to the [code of conduct].
 - About the title: If you had 5 seconds to tell someone the essence of the issue, what would it be?
 
 ### Bugs
 
-- Write out in detail which steps in which order are necessary to reproduce the bug
-- Include environmental information as well, in specific
+- Write out in detail which steps in which order are necessary to reproduce the bug.
+- Include environmental information as well, in specific:
   - How did you install iOwO?
   - What version of iOwO are you running?
   - What operating system are you running?
-    In the case of a Linux distro, mention the specific distro and when you last update as well
-- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump
+    In the case of a Linux distro, mention the specific distro and when you last update as well.
+- If the bug causes a crash, try to get a backtrace or in worse cases, a coredump.
 
 ### Feature requests
 
 - Be sure to include a motivation in which case your intended feature would be used
-  even if it seems obvious to you
-- Estimate what would be needed to implement the feature
+  even if it seems obvious to you.
+- Estimate what would be needed to implement the feature:
   - Is it an addition to the language itself?
   - Is it just a new command?
   - Does it ground-breakingly change how iOwO works?
 
 ## Through a PR
 
-1. Clone the repo
-2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`
-3. Implement your code changes with your favorite code editor
-4. Try them with `cargo run`
-5. If there are errors or warnings, go to step 3. Commit occasionally
+1. Clone the repo.
+2. Switch to a new appropiately named branch for what you want to do, using `git switch -c`.
+3. Implement your code changes with your favorite code editor.
+4. Try them with `cargo run`.
+5. If there are errors or warnings, go to step 3. Commit occasionally.
 6. Otherwise,
   - if you have an account at https://forge.katzen.cafe,
     1. fork the repo
@@ -80,9 +80,9 @@ If you want to contribute art or the like, do that in whatever **you** are most
 
 ### Major decisions
 
-- All current maintainers have to agree **unanimously**
-- Agreement must be based on [informed consent]
-  - In effect, a maintainer has to understand what they agree to
+- All current maintainers have to agree **unanimously**.
+- Agreement must be based on [informed consent].
+  - In effect, a maintainer has to understand what they agree to.
 
 # Interacting with PRs
 
@@ -90,8 +90,8 @@ Remember, be respectful.
 Entities invest their free time and motivation into making these changes,
 treat them appropiately.
 
-- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good
-- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets)
+- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
+- Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets).
 
 ## Initial steps for a new contributor or new local checkout
 
@@ -102,8 +102,8 @@ git remote update <contributor-name>
 
 ## After setting up the remote
 
-- You can repeat this step anytime you want to switch branches or update your local checkout
-- The PR branch is visible just below the PR title on Forgejo, after the colon (`:`)
+- You can repeat this step anytime you want to switch branches or update your local checkout.
+- The PR branch is visible just below the PR title on Forgejo, after the colon (`:`).
 
 ```sh
 git switch <pr-branch>
-- 
2.46.0


From 666b4f9cb68d533a07721610e3108a895111d122 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Sat, 20 Jan 2024 13:39:53 +0100
Subject: [PATCH 24/26] repo(contributing): clarify that tool list is just a
 suggestion

---
 CONTRIBUTING.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f81c296..24fa6ac 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,22 +51,26 @@ The techstack we operate on is
 
 - [typst] for documents and concrete proposals
 - [Rust] for the actual code
-- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
-- [Penpot] for layouting prototypes and the like
 
 So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
 If you want to contribute thoughts and techincal designs, then consider taking a ride through
 [typst's excellent tutorial]!
-If you want to contribute art or the like, do that in whatever **you** are most comfortable with!
+
+For creative things, we suggest using whatever **you're** comfortable with.
+Otherwise, we suggest these:
+
+- [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
+- [Penpot] for layouting prototypes and the like
 
 [typst]: https://typst.app
 [Rust]: https://www.rust-lang.org
+[The Rust Programming Language book]: https://doc.rust-lang.org/book/
+[typst's excellent tutorial]: https://typst.app/docs/tutorial
+
 [Inkscape]: https://inkscape.org/ 
 [GIMP]: https://www.gimp.org/
 [Blender]: https://www.blender.org/
 [Penpot]: https://penpot.app/
-[The Rust Programming Language book]: https://doc.rust-lang.org/book/
-[typst's excellent tutorial]: https://typst.app/docs/tutorial
 
 ## Politics
 
-- 
2.46.0


From 24ffe91b66a542873100d986fbe16e28525719b4 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Sat, 20 Jan 2024 18:23:42 +0100
Subject: [PATCH 25/26] repo(contributing): apply review

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 24fa6ac..3f7b892 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,10 +53,10 @@ The techstack we operate on is
 - [Rust] for the actual code
 
 So if you want to contribute functionality, take a look at [The Rust Programming Language book]!
-If you want to contribute thoughts and techincal designs, then consider taking a ride through
+If you want to contribute thoughts and technical designs, then consider taking a ride through
 [typst's excellent tutorial]!
 
-For creative things, we suggest using whatever **you're** comfortable with.
+For creative things, we suggest using whatever **you** are comfortable with.
 Otherwise, we suggest these:
 
 - [Inkscape], [GIMP] and [Blender] for promotional material like logos and posters
-- 
2.46.0


From 92aa3b4a3a5fc6b260dec1c237686d9988fc53a2 Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Sat, 20 Jan 2024 19:52:23 +0100
Subject: [PATCH 26/26] repo(contributing): simplify wording by removing
 implied info

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3f7b892..a89a2d0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -94,7 +94,7 @@ Remember, be respectful.
 Entities invest their free time and motivation into making these changes,
 treat them appropiately.
 
-- Since in iOwO, we mostly work based on forks, [git's remotes] work fairly good.
+- Since we mostly work based on forks, [git's remotes] work fairly good.
 - Replace things in pointy brackets (`<>`) respectively (and remove the pointy brackets).
 
 ## Initial steps for a new contributor or new local checkout
-- 
2.46.0