From 6e8899966275795d26360174b840e6cff584bb4c Mon Sep 17 00:00:00 2001
From: liquidev <liquidev@tutanota.com>
Date: Wed, 23 Oct 2024 20:12:02 +0200
Subject: [PATCH] document `withDotter` (and reticles) in docs/system.dj

---
 docs/system.dj | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/docs/system.dj b/docs/system.dj
index 74bb2a3..b6abfd7 100644
--- a/docs/system.dj
+++ b/docs/system.dj
@@ -53,8 +53,22 @@ With that said, there are several types of values in haku that can be passed int
   - `shapeLike` - anything that can be turned into a `shape` using `toShape`.
 
 - `scribble` - something that can be drawn on the wall.
+- `reticle` - an interaction the user can make with the wall.
 
-Additionally, the syntax `a | b` may be used to signify that one of the listed types is accepted or returned. 
+The syntax `a | b` may be used to signify that one of the listed types is accepted or returned. 
+
+The following syntax:
+
+```haku
+{
+  A : t
+  B : u
+}
+```
+
+is used for _records_---functions which take in a tag as a parameter, and return a value depending on what tag was passed.
+In the case above, if `A` is passed in a value of type `t` is returned, and if `B` is passed in a value of type `u` is returned.
+Passing in any other tag is an error.
 
 
 ## Math
@@ -670,3 +684,35 @@ fill
 Creates a fill scribble, which fills in the entire area of the provided shape with a solid color.
 
 Since this requires the shape to have a surface area, this does not do anything when point and `line` shapes are passed in.
+
+
+## Reticles
+
+```haku
+withDotter
+  cont : \{
+    To   : vec
+    From : vec
+    Num  : number
+  } -> scribble
+  -> reticle
+```
+
+The dotter is a reticle that allows the user to draw things on the wall directly under the mouse cursor.
+Once the user makes the interaction (presses the left mouse button), `cont` is called repeatedly with every movement of the mouse cursor, until the mouse button is released.
+
+::: aside
+
+It's not called a _plotter_ since the dotter does not plot lines or curves; it only places dots under the mouse cursor.
+
+:::
+
+During the interaction, `cont` is called with a record containing the following fields:
+
+- `To` - the current position of the mouse cursor
+- `From` - the previous position of the mouse cursor. May be equal to `To` if the user just pressed the mouse button.
+- `Num` - the number of times `cont` has been called since the mouse cursor was pressed. Always greater or equal to `0`.
+
+Since the dotter reticle finishes immediately (there is no extra interaction the user needs to take after pressing the mouse button for the action to be taken,) `cont` may only return a scribble; never another reticle.
+
+The drawing area is a large, square, chunk-aligned perimeter around `To`.