diff options
Diffstat (limited to 'docs/typ')
| -rw-r--r-- | docs/typ/command-line.txt | 300 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 13 |
2 files changed, 313 insertions, 0 deletions
diff --git a/docs/typ/command-line.txt b/docs/typ/command-line.txt new file mode 100644 index 00000000..21b218c7 --- /dev/null +++ b/docs/typ/command-line.txt @@ -0,0 +1,300 @@ +pardes: an editor, a terminal multiplexer, and the file tree that scripts both. + +Usage: + pardes [flags] [FILE[:LINE] | DIR | -] open, start a session, or page stdin + pardes COMMAND [ARGS] [-s NAME] a file named like a command: pardes ./ps + +Open: + FILE[:LINE] open it; in a pane, in that pane's session + -w, --wait FILE open it, return when its pane closes (EDITOR='pardes -w') + - stdin into a +Pager, its colours kept + DIR start in it + +Sessions: + ps the daemon's sessions, their clients and shells + attach [NAME] show a detached session here (HOST:NAME: over ssh) + kill NAME end a session and its shells (--all: every one) + new [flags] [FILE] start one: --detach=NAME --9p=NAME -n 3 (help new) + +Words: + do WORD [ARG] run a builtin at this pane, or the session's: do Newcol + words [GROUP] the builtins by group, or one group's: words column + +Files: + fs VERB [PATH] ls read write ask follow stat help complete, on the session's tree + +Self: + help [CMD|WORD|PATH] this, a command, a builtin, or a file of the tree + completion SHELL bash, fish or zsh + skill the guide an agent reads + version this build, its session wire and its 9P + +Flags: + -s, --session NAME the session to act on ($PARDES_9P, else the only one) + -p N the pane, for do ($PARDES_PANE) + +The old spellings --ps, --attach[=NAME], --kill=NAME, --kill-all, -h and +--version still work, for a release. + +== pardes help ps + +What the per-user daemon keeps: each session with its name, pid, kind +(tty or gui) and whether one is attached; under it its clients and its +shells; then the shells no session holds, which Adopt takes. /sessions +is the same list, read from inside a session. + +Usage: + pardes ps + +Examples: + pardes ps every session, client and shell + +See also: attach, kill, /sessions + +== pardes help attach + +Show a detached session here: in this terminal for pardes, a window +for pardes-gui. Bare, the one detached session (with none, the one +session). One attached already, or of the other kind, is joined as a +client. HOST:NAME is a client of session NAME on another machine, +over `ssh -L` to its pardes-replica.sock ($PARDES_SSH: the ssh +command, default ssh; $PARDES_REMOTE_RUNTIME: its runtime directory, +if not this one's path); SOCK:NAME goes through a socket forwarded +already (a path, with a '/'). Returns when the session detaches or +ends. + +Usage: + pardes attach [NAME] + +Examples: + pardes attach the one detached session + pardes attach notes the one started with --detach=notes + pardes attach box:notes on host box, over ssh -L + pardes attach /run/x.sock:notes through a socket forwarded already + +See also: ps, kill, new --detach, the Detach word + +== pardes help kill + +End session NAME (its --9p or --detach name, else its pid) and its +shells: TERM, then KILL 2 s later. Unsaved changes are lost. --all +ends every session and every shell the daemon keeps. + +Usage: + pardes kill NAME + +Examples: + pardes kill notes the session started with --detach=notes + pardes kill --all every session and shell + +See also: ps, attach + +== pardes help new + +Start a session here, even in a pane of another: in this terminal for +pardes, a window for pardes-gui, or with --detach none until one +attaches. Bare `pardes` takes the same flags, and starts one unless +it is in a pane (where it hands its FILE to that session). + +Usage: + pardes new [flags] [FILE] + +Flags: + --tty start as one shell pane already in tty mode + -n COUNT shell panes to start with: 1 (default) or 3 (classic); a FILE boots just that file + --tty-toggle KEY Ctrl-KEY toggles tty and editor mode + -l DUMP load a dump of another instance (see Dump) + --nested a session of its own in a pane of another, serving none of its children + --9p=NAME name the 9P socket (else the --detach name, else the pid); under $XDG_RUNTIME_DIR, else ~/.local/state/pardes: a directory of yours alone + --9p-tcp=tcp!IP!PORT also serve 9P there, a numeric address + --mount=NAME=DIAL a 9P session or Unix/TCP endpoint under /n/NAME; repeat for more; os and self are reserved + --geometry=WxH[+X+Y] the window's size in points, and where it goes where the display lets a window say (X11) + --detach[=NAME] no terminal (no window) until one attaches; panes, shells and files stay; NAME (one path component) rather than the pid. One pardes --daemon per user keeps sessions (PARDES_DAEMON=off: none) + -w, --wait in a pane, hand FILE to its session and return once its pane is deleted: 0, or 1 if the session goes (EDITOR='pardes --wait') + -- the end of the flags: pardes -- -name opens -name + +Examples: + pardes new a session here, its shell pane in tty mode + pardes new --detach=notes one with no terminal, named notes + pardes new -n 3 src/ three shell panes in src/ + pardes new --mount=peer=notes with session notes under /n/peer + +See also: attach, kill, --nested + +== pardes help do + +Write WORD and its ARG to the ctl that takes it, as the session's +/commands says: the root's /ctl for a session's word, a pane's +pane/N/ctl for a pane's, that pane being this shell's ($PARDES_PANE) +or -p N. A refusal prints the session's own words, and the exit is 1. +The session is -s NAME, else $PARDES_9P, else the only one running. + +Usage: + pardes do WORD [ARG] + +Examples: + pardes do Newcol an empty column + pardes do Save -p 3 save pane 3 + pardes do Edit ',x/foo/c/bar/' -p 3 sam's Edit on pane 3 + pardes do Wrap -s notes at session notes + +See also: words, help WORD, /commands + +== pardes help words + +The session's builtins, as its /commands lists them, grouped by the +first key after the leader (SPC f is file, SPC c column): with no key, +a setting, a session's word (its root ctl's) or a text word (a +pane's). An addon's words are the addon group. With no session, the +ones this build has. + +Usage: + pardes words [GROUP] + +Examples: + pardes words every builtin, by group + pardes words column the column words + +See also: do, help WORD, /commands + +== pardes help fs + +The session's file tree, through a 9P client in this binary: the +files a mount or 9p(1) reaches, with a refusal in the session's own +words (a mount says only EINVAL). With no session, ls, stat, help and +complete, and a read of README, commands or ctl, ask a core made in +this process; the rest are a running session's, and say so. + +Usage: + pardes fs VERB [PATH] + +usage: fs ls [PATH] the names in a directory, a / after each directory + fs read PATH the file, to its end (a held read streams) + fs write PATH [WORDS...] the words and a newline, else stdin, as > would + fs ask PATH WORDS... write the words and read the answer on the same open + fs follow PATH [WORDS...] ask, or read: what comes, as it comes, for as long + fs stat PATH mode length uid gid mtime name + fs help [PATH] what the tree's README says of PATH + fs complete [PREFIX] the paths that go on from PREFIX, for a shell + +Examples: + pardes fs ls pane/1 what a pane serves + pardes fs read index a line per pane + pardes fs write pane/3/ctl 'Edit ,x/foo/c/bar/' a write, refused in words + pardes fs ask pane/3/pty/run make exit N, then the output + pardes fs follow log follow events as they come + +See also: help PATH, /README + +== pardes help help + +Bare, this map. A command: what it does, with examples. A builtin: +its /commands line, its key, and how to run it. A path of the tree: +what the tree's README says of it and of what is under it. --all: +every command's help and the README whole, as this build has them +(never a session's), which the reference prints. + +Usage: + pardes help [CMD|WORD|PATH] + +Examples: + pardes help attach a command + pardes help Newcol a builtin + pardes help pane/3/addr a file of the tree + +See also: words, fs help + +== pardes help completion + +A completion script for SHELL, printed, never installed. It asks this +binary back for each word (`pardes completion -- WORDS`): commands, +the builtins after do, sessions after attach and kill, the tree's +paths after fs. + +Usage: + pardes completion SHELL + +Examples: + pardes completion fish | source in fish, for this shell + source <(pardes completion bash) in bash + source <(pardes completion zsh) in zsh + +== pardes help skill + +The guide for an agent that drives pardes, from this binary, so it +matches what it runs: recipes and traps. What is there it leaves to +`pardes help`. + +Usage: + pardes skill + +Examples: + pardes skill + +== pardes help version + +This build's version; the semantics a replica must share with its +session; the 9P its tree speaks. + +Usage: + pardes version + +Examples: + pardes version + +== the old spellings + + --attach[=NAME] pardes attach NAME + --ps pardes ps + --kill=NAME pardes kill NAME + --kill-all pardes kill --all + -h, --help pardes help + --version pardes version + +== pardes help /: the tree's README + +Pardes virtual filesystem +========================= +README this summary; the pardes book's Scripting and Reference chapters have the rest +index a line per pane: serial kind(text|term|cmd|pdf|image|an addon's) dirty name column; names hold blanks: rsplit(maxsplit=1) +status pid, version and pane count +look write a line: a right click on it at the pane with the keyboard; read: the serials it touched (this open's) +exec write a line: a middle click, a builtin or a shell line; read the same (every exec file) +pager write a directory: its one +Pager, made or emptied; read the same open: its serial (pardes -) +log events: new del rename save newcol delcol run exit send ask answer changed dump restore restored restoredcol msg err +screen the rendered screen as JSON, frozen from open to close +listeners the session's dial addresses +sessions the pardes daemon's, as pardes --ps: daemon <pid>; session <pid> tty|gui attached|detached <name>; shell <pid>; orphan <pid> +focus the serial of the pane with the keyboard (empty on a column tag); write one to give it the keyboard +kbdin write runes: keys typed at the pane with the keyboard, done before the write answers (\x1b Esc, \n Enter) +mousein write `m col row buttons` (1 left, 2 middle, 4 right): the mouse as it now is; m 10 5 4, m 10 5 0 is a right click +ctl settings a line; or Newcol, Dump [export f], Restore [label|f], Exit (refuses once over unsaved panes), Kill [w], size C R +commands every builtin: word, arg, root|pane|both (the ctl that takes it), -- what it does; addons: the kinds of pane here +recent files opened lately, closed ones too: open|closed <path> +dumps the dumps the state file keeps, the newest first: <label> <date> <size> <panes> +layout a line per column: serial index x width current|notcurrent empty|full pane-serials; then active <serial> +tag the workspace tag, tagexec a word as a click in it; col/<serial>/ a column's tag, ctl, exec; rmdir: empty only +pane/new open it to make a pane (<session dir>/+New) in the active column; the read answers its serial +pane/<n>/ name body tag ctl addr dot limit data xdata sel dirty mark scroll errors event look exec tagexec; rmdir closes + on terminals pty/data (keys in, output out), pty/status, pty/ctl (winsize, sig, exec), pty/run (a line, its exit and output) +os/ the host filesystem + +$m below: $PARDES_MOUNT (set under 9ns --mntgen); without it, 9p -a "unix!$PARDES_9P". + + cat $m/index which panes exist + n=$(cat $m/pane/new) make a pane of your own (each open makes one), take its serial + exec 3<>$m/pane/$n/look; echo /etc/hosts:3 >&3; cat <&3 open a file through it, see the pane it went to + printf 'text\n' >> $m/pane/$n/body append to it (> replaces it all) + echo 'Msg hello' > $m/pane/$n/exec show text in the editor + echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl sam's Edit, one undo step; an x that matches nothing succeeds + echo /re/ > $m/pane/$n/addr; printf new > $m/pane/$n/data replace the next match + exec 3<>$m/log; echo follow >&3; cat <&3 what happened lately, then wait for more + exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3 exit N, then the output + +Traps: + A refused write says only EINVAL or EIO; grep '^err' log | tail -1 says why (not the last line, maybe +Unsaved's new). + Root look and exec act at the pane with the keyboard, which another client may own: use a pane's own look and exec. + addr is the pane's and moves on: each /re/ searches from the last, a data write leaves it past the text. + Through a mount, printf 'a\nb\n' arrives a line a write: send a block with one write, ending in a newline. + Pane words (Save Undo Del) go to pane/<n>/ctl, settings and session words to /ctl. + Exit, Restore, Del and get refuse once over unsaved text; the same word again discards. diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 7360179f..d359489b 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -1172,6 +1172,19 @@ says the session is gone); with waits there. Bare `pardes` in a pane refuses and names `--nested`, which starts a separate session whose shells do not forward to it. +A first word that names a command is that command instead (a file named +so is `./ps`, or after `--`): `ps`, `attach`, `kill` and `new` for +sessions; `do WORD` and `words` for the builtins of #file("/commands"); +`fs` for the tree, through a 9P client in the binary, a refusal in the +session's own words; `help`, `completion`, `skill` and `version`. A +command that acts on a session takes `-s NAME`, else `$PARDES_9P`, else +the only one running; with none, `help`, `words`, `completion` and a read +of #file("/README"), #file("/commands") or #file("/ctl") ask a core made +in the command's own process. What follows is `pardes help --all`, printed +by the build (docs/typ/command-line.txt), so it is what the binary says. + +#raw(read("command-line.txt"), block: true) + = Placement <placement> A new pane goes in the column whose tag asked, else the active column (last typed or left-clicked in, |
