From 032bc0648f1e62eff4c6debe3cb1878cc89bda24 Mon Sep 17 00:00:00 2001
From: crumbtoo <crumb@disroot.org>
Date: Tue, 14 Nov 2023 11:05:46 -0700
Subject: [PATCH] document a few strs

---
 docs/src/commentary/stg.rst | 99 +++++++++++++++++++++++++++++++++++--
 docs/src/conf.py            |  3 ++
 2 files changed, 97 insertions(+), 5 deletions(-)

diff --git a/docs/src/commentary/stg.rst b/docs/src/commentary/stg.rst
index a5c7b81..e123621 100644
--- a/docs/src/commentary/stg.rst
+++ b/docs/src/commentary/stg.rst
@@ -1,8 +1,26 @@
 The *Spineless Tagless G-Machine*
 =================================
 
-WIP. Here's a typeset state transition rule describing the action of
-dereferencing indirections when passed as function arguments.
+WIP. This will hopefully be expanded into a thorough explanation of the state
+machine.
+
+Evaluation is complete when a single \texttt{NNum} remains on the stack and the
+dump is empty.
+
+.. math::
+   \transrule
+   { a : \nillist
+   & \nillist
+   & h
+   \begin{bmatrix}
+        a : \mathtt{NNum} \; n
+   \end{bmatrix}
+   & g
+   }
+   { \mathtt{HALT}
+   }
+
+Dereference an indirection passed as an argument to a function.
 
 .. math::
    \transrule
@@ -10,7 +28,78 @@ dereferencing indirections when passed as function arguments.
            \begin{bmatrix}
                a : \mathtt{NAp} \; a_1 \; a_2 \\
                a_2 : \mathtt{NInd} \; a_3
-           \end{bmatrix} & f}
-        {a : s & d & h[a : \mathtt{NAp} \; a_1 \; a_3] & f}
-   :label: rule1
+           \end{bmatrix} & g}
+        {a : s & d & h[a : \mathtt{NAp} \; a_1 \; a_3] & g}
+
+Dereference an indirection on top of the stack.
+
+.. math::
+   \transrule
+        {p : s & d & h
+            \begin{bmatrix}
+                p : \mathtt{NInd} \; a
+            \end{bmatrix} & g}
+        {a : s & d & h & g}
+
+Perform a unary operation :math:`o(n)` with internal :code:`Prim` constructor
+:code:`O` on an argument in normal form.
+
+.. math::
+   \transrule
+        { f : a : s
+        & d
+        & h
+        \begin{bmatrix}
+            f : \mathtt{NPrim} \; \mathtt{O} \\
+            a : \mathtt{NAp} \; f \; x \\
+            x : \mathtt{NNum} \; n
+        \end{bmatrix}
+        & g
+        }
+        { a : s
+        & d
+        & h
+        \begin{bmatrix}
+            a : \mathtt{NNum} \; (o(n))
+        \end{bmatrix}
+        & g
+        }
+
+Perform a unary operation :math:`o(n)` with internal :code:`Prim` constructor
+:code:`O` on an unevaluated argument.
+
+.. math::
+   \transrule
+        { f : a : \nillist
+        & d
+        & h
+        \begin{bmatrix}
+            f : \mathtt{NPrim} \; \mathtt{O} \\
+            a : \mathtt{NAp} \; f \; x
+        \end{bmatrix}
+        & g
+        }
+        { b : \nillist
+        & (f : a : \nillist) : d
+        & h
+        & g
+        }
+
+Restore the stack when a sub-computation has completed.
+
+.. math::
+   \transrule
+   { a : \nillist
+   & s : d
+   & h
+   \begin{bmatrix}
+        a : \mathtt{NNum} \; n
+   \end{bmatrix}
+   & g
+   }
+   { s
+   & d
+   & h
+   & g
+   }
 
diff --git a/docs/src/conf.py b/docs/src/conf.py
index 9e9b12f..eab6c79 100644
--- a/docs/src/conf.py
+++ b/docs/src/conf.py
@@ -38,7 +38,10 @@ imgmath_latex_preamble = r'''
          \implies & #2 \\
          \hline
     \end{tblr} }
+
+\newcommand{\nillist}{[\,]}
 '''
+
 imgmath_image_format = 'svg'
 imgmath_font_size = 14