Setting up your environment: a 9ns mount, pardes as the editor, pager and yazi opener, the shells with prompt marks, language servers, fonts and plan9port, each snippet tried

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

2 files changed, 167 insertions, 1 deletions

diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 39e99aa6..55f11a80 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -225,7 +225,7 @@ but may not be read or written) is printed and the command exits 1.
 `pardes --wait FILE` (`-w`) returns when the pane showing FILE is closed
 (exit 0) or the session goes away (exit 1), as acme's `E` does. Set
 `EDITOR='pardes --wait'` (`GIT_EDITOR` follows it), and `git commit`,
-`crontab -e` and fish's Ctrl-O open in a pane and read the file once you
+`crontab -e` and fish's Alt-E open in a pane and read the file once you
 close it. Bare `pardes` inside a pane refuses and names `--nested`, which
 starts a separate session whose shells do not forward to it.
 
diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ
new file mode 100644
index 00000000..8cf8b091
--- /dev/null
+++ b/docs/typ/setup.typ
@@ -0,0 +1,166 @@
+// Setting up your environment: what to put outside pardes (the shell's
+// startup files, a desktop launcher, other programs' configs) so that it
+// 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.
+
+= 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:
+
+#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`.
+
+```
+[Desktop Entry]
+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`:
+
+```
+if status is-interactive; and not set -q NINE_MOUNT
+        and test -e /dev/fuse; and type -q 9ns
+    exec 9ns --mntgen -- fish
+end
+```
+
+bash, in `~/.bashrc`:
+
+```
+if [[ $- == *i* && -z $NINE_MOUNT && -e /dev/fuse ]] && command -v 9ns >/dev/null; then
+    exec 9ns --mntgen -- bash
+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:
+
+#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`.
+
+= A pager <pager>
+
+// PENDING: written to the 9P agent's pager design, which is not on main
+// yet; check every line against its change when it lands.
+`pardes -` reads its standard input into a `+Pager` pane. Terminal panes
+get `PAGER='pardes -'` and `GIT_PAGER='pardes -'` by themselves, unless
+your environment sets them, so `git log` or `man` output arrives as a pane
+to search and click in; command panes get `cat`. `Pager off` (on the root
+ctl, or a line in the startup file) turns it off, `Pager pardes` back on.
+To keep your own pager in pardes's terminals, set `PAGER` in your
+environment; to use pardes's outside them, set it to `pardes -` yourself.
+
+= 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):
+
+```
+[opener]
+pardes = [
+  { run = 'pardes %s', desc = "Open in pardes", for = "unix" },
+]
+
+[open]
+prepend_rules = [
+  { mime = "text/*", use = "pardes" },
+]
+```
+
+`%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.
+
+= Shells <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`.
+
+= 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.
+
+#pairs(
+  [`.zig`], [`zls` (`PARDES_LSP_ZIG`)],
+  [`.rs`], [`rust-analyzer` (`PARDES_LSP_RS`)],
+  [`.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`)],
+)
+
+#word("Lspinfo") (#key("SPC l i")) says which server serves the file and
+what state it is in.
+
+= 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")).
+
+= 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:
+
+#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.