From d3638abbb3d177ea08beed3b09cd9682b3732daf Mon Sep 17 00:00:00 2001
From: Gabriel Schneider <gbrls@0x4200.cafe>
Date: Thu, 1 Oct 2026 11:03:21 -0300
Subject: The docs give back the day-one lines the trim cut, the tutor becomes
 exercises on a +Tutor copy, the README builds the GUI and says what a
 terminal needs, and Shift-Esc says it needs the kitty keyboard protocol

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/typ/scripting.typ | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

(limited to 'docs/typ/scripting.typ')

diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index d5400f50..9b67ac76 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -39,11 +39,13 @@ else
     rd() { 9p -a "unix!$PARDES_9P" read "$1"; }
     wr() { 9p -a "unix!$PARDES_9P" write "$1"; }
 fi
-f=$(rd pane/$n/name)
+f=$(rd pane/$n/name)    # the file it shows
 case $f in *.go) ;; *) echo "Fmt: $f is not Go" >&2; exit 1 ;; esac
 echo Save | wr pane/$n/ctl && gofmt -w "$f" && echo get | wr pane/$n/ctl
 ```
 
+`get` on a pane's ctl reloads its text from the file on disk.
+
 Type `Fmt` into a Go pane's tag and click it with #btn("B2"); its output
 shows in a command pane. To have `Fmt` in every Go file's tag, follow the
 log and add it to each new `.go` pane (with a mount):
@@ -60,10 +62,11 @@ done
 
 = Recipes
 
-Each recipe starts after these lines, which find the session and make a
-pane of your own (`rmdir $p` closes it). Work through that pane's
-#file("look") and #file("exec"), not the root's:
-#cmd("s=${PARDES_9P##*/pardes-9p-}; m=$NINE_MOUNT/pardes/${s%.sock}\nn=$(cat $m/pane/new); p=$m/pane/$n")
+Each recipe starts after the session line above and this one, which makes
+a pane of your own: reading #file("pane/new") makes a pane and answers its
+serial, and `rmdir $p` closes it. Work through that pane's #file("look")
+and #file("exec"), not the root's:
+#cmd("n=$(cat $m/pane/new); p=$m/pane/$n")
 
 #pairs(
   [look around], [#cmd("cat $m/index\ncat $m/layout\ncat $m/focus\ncat $m/commands")],
@@ -90,7 +93,10 @@ open stays open: read its #file("body") before you close it. In
 
 Holding a pane's #file("event") open takes its #btn("B2") and #btn("B3")
 clicks: they arrive as acme's records instead of acting, and writing a
-record back has pardes do it (#doc("fs", section: "event")). This helper
+record back has pardes do it. A record is a line, `MX31 36 1 5 Upper`: who
+(`M` mouse, `K` keyboard, `E` or `F` a write to a file), what (`X` execute or `L` look
+in the body, `x` `l` in the tag), the range, a flag, the text's length and
+the text (#doc("fs", section: "event")). This helper
 gives pane `$1` the tag words `Upper` (upper-case the selection) and
 `Done`; every other click is written back, and when it ends the pane's
 clicks are pardes's again:
@@ -98,7 +104,7 @@ clicks are pardes's again:
 ```bash
 #!/bin/bash
 # upper PANE: own the tag words Upper and Done in pane PANE
-s=${PARDES_9P##*/pardes-9p-}; p=$NINE_MOUNT/pardes/${s%.sock}/pane/$1
+s=${PARDES_9P##*/pardes-9p-}; m=$NINE_MOUNT/pardes/${s%.sock}; p=$m/pane/$1
 printf ' Upper Done' >> $p/tag
 exec 3<>$p/event                        # hold event on fd 3, this shell's own
 while IFS= read -r rec <&3; do
-- 
cgit v1.3