From 10886be00ae79b3e4db31b6d66fa8ef29fb4a46c Mon Sep 17 00:00:00 2001
From: MultisampledNight <contact@multisamplednight.com>
Date: Sun, 21 Jan 2024 22:11:41 +0100
Subject: [PATCH] docs(design): add term list

---
 docs/design/iowo-design.typ | 80 ++++++++++++++++++++++++++++++++++---
 docs/template.typ           |  7 ++--
 2 files changed, 78 insertions(+), 9 deletions(-)

diff --git a/docs/design/iowo-design.typ b/docs/design/iowo-design.typ
index c05db3c..0645bee 100644
--- a/docs/design/iowo-design.typ
+++ b/docs/design/iowo-design.typ
@@ -7,6 +7,74 @@
   subtitle: [don't worry, we're just dreaming],
 )
 
+= Term overview
+
+/ Processing stages:
+  Whole workflow of iOwO,
+  from the source to evaluation.
+
+/ Source:
+  Nice textual representation of what iOwO is supposed to do.
+  Consists of instructions and pipelines.
+
+/ Graph IR:
+  Intermediate machine-readable representation of the source.
+  Can be modified by the optimizer
+  and is evaluated or "ran" by the runtime.
+
+/ Optimizer:
+  Simplifies the graph IR and makes it faster to run.
+
+/ Runtime:
+  All-encompassing term for what's done
+  after a graph IR is optimized and fully ready to go.
+
+/ Scheduler:
+  Looks at the graph IR
+  and decides which evaluator gets to run which part of it.
+
+/ Evaluator:
+  One specific implementation of how to run
+  through the whole graph IR to get its results.
+
+/ Function:
+  On the source level and before the graph IR,
+  anything that can be run with inputs,
+  possibly receiving outputs.
+
+/ Instruction:
+  Function, but in the graph IR and at runtime.
+  Ask schrottkatze on why the differentiation is important.
+
+/ Input:
+  Received by a function or instruction.
+  Different inputs may result in different behavior
+  and/or in different outputs.
+
+/ Argument:
+  On the source level,
+  an input which is given ad-hoc
+  instead of provided through a pipeline.
+
+/ Output:
+  Returned by a function or instruction,
+  and can be fed into other functions or instructions.
+
+/ Consumer:
+  Function or instruction that takes at least 1 input.
+
+/ Streamer:
+  Function or instruction that returns at least 1 output.
+
+/ Modifier:
+  Function or instruction that is _both_ a consumer and a streamer.
+
+/ Pipeline:
+  Any chain of streamers and consumers,
+  possibly with modifiers in-between,
+  that may branch out
+  and recombine arbitrarily.
+
 = Processing stages
 
 #graphics.stages-overview
@@ -152,17 +220,17 @@ Merges and simplifies functions in the graph IR.
 == Runtime <runtime>
 
 Runs through all functions in the graph IR.
-It does not have any significantly other representation,
+It does not have any significantly different representation,
 and despite its name there's _no_ bytecode involved.
 
-Different runtimes are called evaluators.
-Evaluators operate on instructions instead of functions.
-
 === Scheduler
 
-Looks at the graph IR and decides when the VM should evaluate what.
+Looks at the graph IR and decides when which evaluator gets to evaluate what.
 
-=== VM <vm>
+=== Evaluator
+
+Runs instructions given to it in a specific way,
+such as for example on the GPU using OpenCL.
 
 = Open questions
 
diff --git a/docs/template.typ b/docs/template.typ
index 0402015..cedb5e6 100644
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -33,22 +33,23 @@
 // this'd require wrapping the whole document in a show rule
 // at which point `query` doesn't find anything anymore
 #let terms = (
+  "processing stage",
   "source",
   "AST",
   "graph IR",
   "runtime",
-  "evaluator",
 
   "optimizer",
   "scheduler",
-  "VM",
+  "evaluator",
+  "evaluation",
 
   "function",
   "instruction",
-  "pipeline",
   "input", "argument", "consumer",
   "output", "streamer",
   "modifier",
+  "pipeline",
 )
 // yes, the shadowing is intentional to avoid accidentally using the list
 #let terms = regex("\\b(" + terms.map(expand).join("|") + ")\\b")