1 files changed, 29 insertions, 0 deletions
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index 22d6349c..03496ee2 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -107,6 +107,31 @@ it. The keyboard is never taken, and the clicks come back when the helper
 closes the file. One open at a time; the record format is in the reference
 (#doc("fs", section: "event")).
 
+This helper gives pane `$1` two tag words of its own: `Upper` upper-cases
+the selection and `Done` ends it. Every other click is written back, so it
+acts as ever, and when the helper ends, its pane's 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
+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
+    read -r head q1 flag n text <<< "$rec"  # e.g. Mx31 36 1 5 Upper
+    case $head$text in
+    [EFKM][Xx]*Upper) sel=$(cat $p/sel); printf %s "${sel^^}" > $p/sel ;;
+    [EFKM][Xx]*Done) break ;;
+    [EFKM][XxLl]*) printf '%s\n' "$rec" >&3 ;;  # not ours: do what it would
+    esac                                # I D i d report edits: nothing to do
+done
+exec 3<&-                               # let event go: clicks act again
+```
+
+`read` takes a record a line, which suits words; a helper that must take
+text holding newlines (a sweep over several lines) reads the record's `n`
+bytes of text itself, with `read -N`.
+
 == Waiting for an edit
 
 `pardes --wait FILE` in a pane's shell returns when the pane showing FILE
@@ -132,6 +157,10 @@ pardes the editor of every program run there.
   the bad one fails. Send a block as one write (`cat block > $p/ctl`), and
   end every write whose result matters with a newline.
 - plan9port's `9p write` opens with OTRUNC: `echo x | 9p write pane/3/body` replaces the whole body. Append with `>>` through a mount.
+- Read #file("event") on a descriptor your shell owns
+  (`exec 3<>$p/event` ... `exec 3<&-`), never `cat $p/event | while read`:
+  the `cat` outlives the loop and holds #file("event") open, so the pane's
+  next click goes to it and is lost.
 - `tail -f log` never sees anything new: write `follow` on the open you
   read. Through a FUSE mount bash's `read -t` cannot time out: wrap the
   loop in `timeout`.