From 3d8fc0733cd2d2c8a6209514aa1158cbd713be25 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Mon, 28 Sep 2026 11:05:26 -0300 Subject: docs: the README and skill answer what dogfooding asked A first-time user through a mount could not find how to get a terminal, read path++text as a typo, did not know > on data replaces only the addressed range, which regexps addr takes, that lock fails fast, what errors is, where an unknown exec word goes (typed into a terminal, not an error), that new panes are +New and a column's last pane leaves one, or which 9ns mount other processes can see. The README (still 45 lines), docs/fs.md and the skill now say. Co-Authored-By: Claude Opus 5.5 --- src/fs-help.txt | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'src/fs-help.txt') diff --git a/src/fs-help.txt b/src/fs-help.txt index 3f7357d4..8db1e288 100644 --- a/src/fs-help.txt +++ b/src/fs-help.txt @@ -1,45 +1,45 @@ Pardes control filesystem ========================= README this guide -index one line per pane: serial, kind (text|term|pdf|image), dirty flag, name +index one line per pane: serial, kind (text|term|pdf|image), dirty flag, name (+New if unnamed) status pid, version and pane count look write a line: a right click on it at the active pane; read: the serials it touched exec write a line: a middle click, an editor command word or a shell line; read the same -log recent events: new/del/rename/save , msg ; write follow to wait +log events: new/del/rename/save , msg , err screen rendered screen as JSON, frozen from open to close listeners the session's dial addresses focus the serial of the pane with the keyboard; write a serial to give it the keyboard ctl the settings, one a line as a write takes them; write one, or Newcol, Dump; Kill QUITS commands every builtin: its word, arg if it takes one, and root or pane: which ctl takes it -pane/new open it to make a pane; the read answers that pane's serial -pane// name body tag ctl addr dot limit data xdata sel dirty mark scroll - errors event look exec, and pty/ for terminals; rmdir closes it +pane/new open it to make a pane (named +New); the read answers that pane's serial +pane// name body tag ctl addr dot limit data xdata sel dirty mark scroll errors (write-only: + appended to its directory's +Errors pane) event look exec, pty/ on terminals; rmdir closes os/, src/ the host filesystem; the editor's own sources (-Dembed-sources=true builds only) -Below, $m is the mount point (PARDES_MOUNT in a Tty9p shell; 9ns and 9p work too): +Below, $m is the mount (/mnt/9p/pardes/ via 9ns --mntgen; PARDES_MOUNT in a Tty9p shell): cat $m/index which panes exist n=$(cat $m/pane/new) make a pane, take its serial echo /etc/hosts:3 > $m/look; cat $m/look open a file, see the pane it went to - printf 'text\n' > $m/pane/$n/body append to a pane (>| truncates first) - cat $m/pane/$n/name; echo notes.txt > $m/pane/$n/name read, then rename - echo Save > $m/pane/$n/exec save it; rmdir $m/pane/$n closes it + printf 'text\n' >> $m/pane/$n/body append to a pane (> replaces it all) + echo notes.txt > $m/pane/$n/name; echo Save > $m/pane/$n/ctl rename, then save it echo 'Msg hello' > $m/exec show text in the editor - echo '#0,#5' > $m/pane/$n/addr; printf NEW >> $m/pane/$n/data replace bytes 0..5 + echo '/^fn/' > $m/pane/$n/addr; printf NEW > $m/pane/$n/data replace what addr matched cp $m/pane/$n/addr $m/pane/$n/dot; cat $m/pane/$n/sel select the range, read it exec 3<>$m/log; echo follow >&3; cat <&3 what happened lately, then wait for more cat $m/pane/$n/event hold it open to own that pane's clicks - echo exec > $m/pane/$n/pty/ctl restart a shell; also winsize C R, sig INT + echo Tty > $m/pane/$n/ctl; cat $m/index a terminal in that pane's directory exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3 exit N then its output; or busy, or error printf 'ls\r' > $m/pane/$n/pty/data type into a terminal; pty/status: cols rows busy + echo 'sig INT' > $m/pane/$n/pty/ctl interrupt it; also winsize C R, and exec to restart Pitfalls, one each: - Each open of pane/new makes another pane (ls, stat, find never do); a reread names the same. - rmdir closes a pane even when it is dirty; index and pane//dirty show the flag. - addr, dot and limit read the same pair of offsets they take, so cp between them works. - dirty, mark and scroll read "0" or "1" and take "0" or "1"; truncating limit lifts it. - body: >> appends, > replaces it all. data: > replaces (and : > deletes) just the addr range. - tag reads path++text; writes append to the text (newlines too); truncating clears it, and dot or addr. + Each open of pane/new makes another pane (ls, stat, find never do); rmdir closes even a dirty one. + addr takes #n,#m or sam-style /regexp/ (^ $ per line); a failed one makes data refuse until reset. + data: > replaces just the addr range and : > deletes it; body: > empties the whole buffer. + tag reads the path, then the tag's own text; writes append to that text; truncating clears it. A terminal's body is a history snapshot frozen per open; pty/data is the live stream. - A failing command is reported in the editor and in log, not as a write error; a bad line fails the write. - pane//ctl: acme's status line + current; takes get, lock/unlock (on a held fd) and pane builtins (Del). + exec: a word no builtin knows is typed into a terminal in the pane's directory, and not an error. + A refused write reads as EINVAL through a mount: the log's err record says why. + lock/unlock on a pane's ctl need a held fd (exec 3>ctl); a lock someone holds fails: retry. + Closing a column's last pane leaves a +New in its place; Delcol closes the column. -- cgit v1.3