The docs trimmed to their path: a guide with Words you'll see and one Where commands run and panes go table, scripting's first tag word Fmt and eight traps, setup as the one home of the pager and the servers, a scannable cheatsheet, an honest README, the edge cases moved to the reference, and the pager's colours

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 51 insertions, 86 deletions

diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ
index 60ea33cd..45767757 100644
--- a/docs/typ/setup.typ
+++ b/docs/typ/setup.typ
@@ -3,31 +3,22 @@
 // works best. Each snippet says in one line why it is there.
 #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
 
-pardes runs as it is, but a few lines elsewhere make it fit: a mount so
-scripts see the session as files, pardes as the editor and file opener of
-other programs, and the servers and fonts it looks for.
+pardes runs as it is; a few lines elsewhere make it fit.
 
 = A 9P mount: 9ns <ninens>
 
-`9ns` is cloud9's 9P namespace tool: it mounts a 9P tree through FUSE in a
-private mount namespace, as a plain user, and runs a program inside. Get it
-from cloud9 (`git.sr.ht/~gbrls/cloud9`): its `zig build` builds `9ns` on
-Linux into `zig-out/bin`, and Linux needs `/dev/fuse`. With `--mntgen` it
-mounts the whole registry of posted 9P servers at `/mnt/9p` and exports
-`$NINE_MOUNT`; every pardes session posts itself there, as
-`$NINE_MOUNT/pardes/<pid or name>`.
-
-Run pardes inside one, and the editor and everything it starts (its
-terminals, command panes, the programs they run) see `$NINE_MOUNT` and the
-session tree, so scripting is just files:
+`9ns`, from cloud9 (`git.sr.ht/~gbrls/cloud9`, whose `zig build` builds it
+on Linux; it needs `/dev/fuse`), mounts 9P trees through FUSE as a plain
+user. With `--mntgen` it mounts every posted session at `/mnt/9p` and
+exports `$NINE_MOUNT`; a pardes session is `$NINE_MOUNT/pardes/<pid or
+name>`. Run pardes inside one, and everything it starts sees the session
+as files:
 
 #cmd("9ns --mntgen -- pardes-gui")
 
-A desktop launcher (`~/.local/share/applications/pardes.desktop`) that
-does it, and still starts pardes on a machine with no 9ns or no
-`/dev/fuse`. Write your own absolute paths: a launcher's `Exec` line takes
-a `$` only escaped, and a desktop session's `PATH` may not hold
-`~/.local/bin`.
+A desktop launcher that still starts pardes without 9ns or `/dev/fuse`
+(absolute paths: `Exec` takes a `$` only escaped, and a desktop `PATH` may
+lack `~/.local/bin`):
 
 ```
 [Desktop Entry]
@@ -35,13 +26,9 @@ Type=Application
 Name=pardes
 Exec=/bin/sh -c "if [ -x /home/me/.local/bin/9ns ] && [ -e /dev/fuse ]; then exec /home/me/.local/bin/9ns --mntgen -- /home/me/.local/bin/pardes-gui; else exec /home/me/.local/bin/pardes-gui; fi"
 Terminal=false
-Categories=Development;
 ```
 
-A shell can wrap itself, so every interactive shell has the mount (and the
-terminal pardes runs in, with the pardes inside it). It checks `$NINE_MOUNT`
-first, so a shell already inside a mount does not wrap again. fish, in
-`~/.config/fish/config.fish`:
+Or let every interactive shell wrap itself, once. fish, in `config.fish`:
 
 ```
 if status is-interactive; and not set -q NINE_MOUNT
@@ -60,41 +47,33 @@ fi
 
 = pardes as your editor <editor-setup>
 
-`pardes --wait FILE` opens FILE in the session whose pane it runs in and
-returns when you close that pane; outside pardes it starts an editor of its
-own, which also returns when you are done. Set it as the editor, and every
-program that asks for one opens a pane:
+`pardes --wait FILE` opens FILE as a pane and returns when you close it
+(outside pardes, it starts an editor that returns when you are done):
 
 #cmd("set -gx VISUAL 'pardes --wait'; set -gx EDITOR 'pardes --wait'   # fish")
 #cmd("export VISUAL='pardes --wait' EDITOR='pardes --wait'            # bash, zsh")
 
-`git commit` (`GIT_EDITOR`, then `core.editor`, then these), `crontab -e`
-and fish's `edit_command_buffer` (Alt-E or Alt-V) read `VISUAL` before
-`EDITOR`, so set both, or a `VISUAL` left from elsewhere wins. To edit the
-command line with Ctrl-O in fish instead, add `bind ctrl-o edit_command_buffer` to `fish_user_key_bindings`.
+`git commit`, `crontab -e` and fish's `edit_command_buffer` (Alt-E) read
+`VISUAL` before `EDITOR`, so set both.
 
 = A pager <pager>
 
 `pardes -` reads its standard input into the directory's one `+Pager`
-pane, escapes stripped, and returns; the next paged text refills it. With
-`Pager pardes` (the default) a terminal's shell gets `PAGER`, `GIT_PAGER`
-and `SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when
-it needs it), and `SYSTEMD_PAGERSECURE=0` (it has no shell escape), each
-only where your environment does not set it. So `git log`, `journalctl` or
-`man` output arrives as a pane to search and click in, a diff (`git diff`,
-`git show`, `git log -p`) drawn as one, and the terminal is back at once;
-command panes page through `cat`. `man` pages through `MANPAGER` first,
-then `PAGER`, and pardes never sets `MANPAGER`: your own `MANPAGER` wins,
-as does any `PAGER`, `GIT_PAGER` or `SYSTEMD_PAGER` of yours. To keep your
-own pager, set it in your environment, or put `Pager off` in the startup
-file (or write it to the root ctl); it applies to terminals started after
-it. Outside pardes, `PAGER='pardes -'` opens a new editor on the text.
+pane, colours kept, and returns. With `Pager pardes` (the default) a
+terminal's shell gets `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to it,
+and `SYSTEMD_PAGERSECURE=0`, each only where your environment does not set
+it. So `git log`, `journalctl` or `man` output arrives as a pane to search
+and click in, a diff drawn as one; command panes page through `cat`. `man`
+reads `MANPAGER` first, which pardes never sets. Any pager of your own wins;
+`Pager off` in the startup file keeps them all yours, for terminals started
+after it. git colours what it pages by default (`color.pager`); ask other
+programs for colour outright (`ls --color=always | pardes -`), and put
+`PagerColor off` in the init file for plain text.
 
 = yazi in a terminal pane <yazi>
 
-yazi, run in a terminal pane, can open files as panes of the session: an
-opener that runs `pardes` forwards each file to the session and returns at
-once. In `~/.config/yazi/yazi.toml` (yazi 26):
+In `~/.config/yazi/yazi.toml` (yazi 26), an opener that forwards files to
+the session as panes:
 
 ```
 [opener]
@@ -108,30 +87,24 @@ prepend_rules = [
 ]
 ```
 
-`%s` is the selected files (older yazi spelled it `"$@"`). yazi's own
-`edit` opener runs `$EDITOR` and waits, so with `EDITOR='pardes --wait'`
-it already opens a pane and blocks until you close it; the opener above
-does not wait. Without a file manager, #btn("B3") on a path in any pane
-(an `ls`, a `find`, a compiler's message) does the same.
+yazi's own `edit` opener runs `$EDITOR` and waits, so `EDITOR='pardes
+--wait'` already opens a pane there. Without a file manager, #btn("B3") on
+a path does the same.
 
-= Shells <shells>
+= Shells and PATH <shells>
 
-pardes injects OSC 133 prompt marks into bash and fish, sourcing your own
-`~/.bashrc` and `config.fish` first: they tell it where each prompt and
-command starts and ends. That is what makes #key("Esc") at a prompt go back
-a pane only when nothing is typed, and #file("pty/run") answer `exit N`
-and the output. Other
-shells (zsh, sh, dash, ksh, nu and the rest) get no marks, and marks a shell
-emits on its own do not count: #file("pty/run") answers `error no prompt marks`, and a prompt counts as free whenever no program holds the terminal,
-typed text or not. Running `exec zsh` inside a bash pane loses the marks
-the same way. The #word("Shell") setting picks the shell; bare, it is
-`$SHELL` if that is executable, else `/bin/sh`.
+pardes injects OSC 133 prompt marks into bash and fish (after your own
+`~/.bashrc` and `config.fish`); they make #key("Esc") at an empty prompt
+and #file("pty/run") work. Other shells, or `exec zsh` inside a bash pane,
+get none: #file("pty/run") answers `error no prompt marks`. Terminals and
+command panes inherit pardes's environment, its `PATH` included, so a
+script on that `PATH` is a word you can click.
 
 = Language servers <language-servers>
 
-pardes starts a language server as a child process for a file it knows,
-looking for the program on `PATH`; `PARDES_LSP_<LANG>` names another
-program, and an empty value turns that language off.
+pardes starts a language server for a file it knows, finding the program
+on `PATH`; `PARDES_LSP_<LANG>` names another, and an empty value turns it
+off.
 
 #pairs(
   [`.zig`], [`zls` (`PARDES_LSP_ZIG`)],
@@ -139,33 +112,25 @@ program, and an empty value turns that language off.
   [`.c .h .cc .cpp .hpp .cxx .hxx`], [`clangd` (`PARDES_LSP_C`)],
   [`.go`], [`gopls` (`PARDES_LSP_GO`)],
   [`.ts .tsx .js .jsx .mjs .cjs`], [`typescript-language-server --stdio` (`PARDES_LSP_TS`)],
-  [`.py`], [`pyright-langserver --stdio`, from pyright (`PARDES_LSP_PY`)],
+  [`.py`], [`pyright-langserver --stdio` (`PARDES_LSP_PY`)],
 )
 
-#word("Lspinfo") (#key("SPC l i")) says which server serves the file and
-what state it is in.
+#word("Lspinfo") (#key("SPC l i")) says what is running.
 
 = Fonts and themes <fonts-and-themes>
 
-The terminal build draws in your terminal's font. The SDL window
-(`pardes-gui`) carries Adwaita Mono and finds others in `/usr/share/fonts`,
-`/usr/local/share/fonts`, `~/.local/share/fonts` and `~/.fonts`, with no
-fontconfig: `Fonts` lists them, and `Font name:size` (size
-8-72) picks one, a line for the startup file. Themes are a word away:
-`Theme <name>`, or `ThemeFile themes/mine.zon` for your own, reloaded as
-you save it (#doc("themes")).
+The terminal build uses your terminal's font. The SDL window carries
+Adwaita Mono and finds others in `/usr/share/fonts`,
+`/usr/local/share/fonts`, `~/.local/share/fonts` and `~/.fonts`; `Font
+name:size` picks one. `Theme <name>` and `ThemeFile` are in the themes
+chapter (#doc("themes")).
 
 = plan9port <plan9port>
 
-plan9port's `9p` reads and writes a session without any mount, which is
-what a script uses when `$NINE_MOUNT` is not set:
+Without a mount, plan9port's `9p` reads and writes a session:
 
 #cmd("9p -a \"unix!$PARDES_9P\" read index")
-#cmd("echo Save | 9p -a \"unix!$PARDES_9P\" write pane/3/ctl")
 
-Its `write` always opens with OTRUNC, so `9p write pane/3/body` replaces the
-whole body where acme would append: append through a mount with `>>`.
-acme habits carry over: `pardes FILE` in a pane is acme's `B`,
-`pardes --wait` is `E`, the files have acme's names (`body`, `tag`, `ctl`,
-`addr`, `data`, `event`), and a program holding a pane's #file("event")
-takes its clicks, as acme's `win` and its friends do.
+acme habits carry over: `pardes FILE` is acme's `B`, `pardes --wait` its
+`E`, the files have acme's names, and a program holding a pane's
+#file("event") takes its clicks, as `win` does.