summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/typ/command-line.txt300
-rw-r--r--docs/typ/reference.typ13
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,