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?
+- @runtime
-  - Or should that be done instead using a debug `show` instruction or the like?
+  - 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

docs/template.typ

@@ -37,11 +37,13 @@
   "AST",
   "graph IR",
   "runtime",
+  "executor",
 
   "optimizer",
   "scheduler",
   "VM",
 
+  "function",
   "instruction",
   "pipeline",
   "input", "argument", "consumer",