From 69238915c7461c64a4678642c920583fd4d057ad Mon Sep 17 00:00:00 2001
From: Gabriel Schneider <gbrls@0x4200.cafe>
Date: Thu, 1 Oct 2026 01:03:47 -0300
Subject: Every scripting and setup recipe runs as written: fmt-here finds the
 session itself, the recipes share one stated preamble, run a command waits
 for its tag, and setup says man reads MANPAGER first

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

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

diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index d3e42573..22d6349c 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -48,26 +48,53 @@ Both hold only where your environment names no pager.
 
 = Recipes
 
-The paths below are under `$m`; `p=$m/pane/$n` for a pane.
+Each recipe starts after these lines, which find the session (with a mount)
+and name a text pane by its serial (from #file("index"), or one you made):
+#cmd("s=${PARDES_9P##*/pardes-9p-}; m=$NINE_MOUNT/pardes/${s%.sock}\nn=3; p=$m/pane/$n")
 
 #pairs(
   [look around], [#cmd("cat $m/index\ncat $m/layout\ncat $m/focus\ncat $m/commands")],
   [open a file at a place], [#cmd("echo \"$PWD/main.zig:120\" > $m/look; cat $m/look # where it went\necho 'main.zig:0/fn main/' > $m/look # the first match")],
   [make, fill, name, save], [#cmd("n=$(cat $m/pane/new) # one pane per open\nprintf 'hello\\n' > $m/pane/$n/body # > replaces, >> appends\necho \"$PWD/notes.txt\" > $m/pane/$n/name\necho Save > $m/pane/$n/ctl\nrmdir $m/pane/$n # close it")],
   [say something], [#cmd("echo 'Msg hello' > $m/exec")],
-  [replace everywhere], [#cmd("echo 'Edit ,x/foo/c/bar/' > $p/ctl && grep -c foo $p/body")],
+  [replace everywhere], [#cmd("echo 'Edit ,x/foo/c/bar/' > $p/ctl\ngrep -c foo $p/body # 0: none left")],
   [replace one match], [#cmd("echo /old/ > $p/addr && printf new > $p/data")],
   [delete line 3], [#cmd("echo 3 > $p/addr; : > $p/data")],
   [select line 3, read it], [#cmd("echo 3 > $p/addr; cp $p/addr $p/dot; cat $p/sel")],
-  [run a command], [#cmd("echo 'make test' > $m/exec; c=$(cat $m/exec) # its pane\ngrep \"^exit $c \" $m/log | tail -1 # exit c N")],
+  [run a command], [#cmd("echo 'make test' > $m/exec; c=$(cat $m/exec) # its pane\nuntil grep -q ') exit ' $m/pane/$c/tag; do sleep 0.2; done\ngrep -o 'exit [0-9?]*' $m/pane/$c/tag")],
   [run at a prompt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nexec 3<>$m/pane/$t/pty/run; echo ls >&3; cat <&3; exec 3<&-")],
-  [type, interrupt], [#cmd("printf 'q' > $m/pane/$t/pty/data # \\r Enter, \\x03 Ctrl-C\necho 'sig INT' > $m/pane/$t/pty/ctl")],
+  [type, interrupt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nprintf 'q' > $m/pane/$t/pty/data # \\r Enter, \\x03 Ctrl-C\necho 'sig INT' > $m/pane/$t/pty/ctl")],
   [ask the language server], [#cmd("echo /myFunc/ > $p/addr; echo dot=addr > $p/ctl\necho Hover > $p/exec # also Rename new, Symbols")],
-  [act on the pane a command came from], [#cmd("#!/bin/sh\n# fmt-here: put its name in a pane's tag, click it with B2\nn=$winid; f=$(cat $m/pane/$n/name)\necho Save > $m/pane/$n/ctl && zig fmt \"$f\" && echo get > $m/pane/$n/ctl")],
   [follow what happens], [#cmd("exec 3<>$m/log; echo 'follow new' >&3\ntimeout 30 cat <&3; exec 3<&-")],
 )
 
-`follow` without `new` replays the ring first. #file("pty/run") answers
+`follow` without `new` replays the ring first.
+
+== A script for a tag
+
+A script can act on the pane it was clicked from through `$winid`. This
+one saves a Zig file, formats it and loads the result: put it on your
+`PATH` as `fmt-here`, type `fmt-here` into a pane's tag and click it with
+#btn("B2"). It follows the one-client rule itself, since a script starts
+with nothing set but its environment:
+
+```sh
+#!/bin/sh
+# fmt-here: save the pane it was clicked from, zig fmt its file, reload it
+n=$winid
+if [ -n "$NINE_MOUNT" ]; then
+    s=${PARDES_9P##*/pardes-9p-}; m=$NINE_MOUNT/pardes/${s%.sock}
+    rd() { cat "$m/$1"; }
+    wr() { cat > "$m/$1"; }
+else
+    rd() { 9p -a "unix!$PARDES_9P" read "$1"; }
+    wr() { 9p -a "unix!$PARDES_9P" write "$1"; }
+fi
+f=$(rd pane/$n/name)
+echo Save | wr pane/$n/ctl && zig fmt "$f" && echo get | wr pane/$n/ctl
+```
+
+Its output, and `exit 0`, show in the command pane it runs in. #file("pty/run") answers
 `busy: <program> is running` when a program holds the terminal: talk to it
 through #file("pty/data") instead.
 
-- 
cgit v1.3