From 06770c54a408057c92c0381b75039d70c85625d6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 00:02:33 -0300 Subject: 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 --- docs/typ/setup.typ | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/typ/setup.typ (limited to 'docs/typ/setup.typ') 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 + +`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/`. + +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 + +`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 + +// 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, 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 + +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 + +pardes starts a language server as a child process for a file it knows, +looking for the program on `PATH`; `PARDES_LSP_` 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 + +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 `, or `ThemeFile themes/mine.zon` for your own, reloaded as +you save it (#doc("themes")). + += 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. -- cgit v1.3