diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-30 17:35:06 -0300 |
| commit | 6d8da8721141284cf33bb901168b26135893eb86 (patch) | |
| tree | 791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/typ/setup.typ | |
| parent | efd43a3a2cf03bb741366331158b368abf9ac583 (diff) | |
| parent | bf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff) | |
| download | pardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz pardes-6d8da8721141284cf33bb901168b26135893eb86.zip | |
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/typ/setup.typ')
| -rw-r--r-- | docs/typ/setup.typ | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ new file mode 100644 index 00000000..f49c9075 --- /dev/null +++ b/docs/typ/setup.typ @@ -0,0 +1,136 @@ +// 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 + += Install <install> +#include "install.typ" + += A 9P mount: 9ns <ninens> + +`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's +virtual filesystem as files: + +#cmd("9ns --mntgen -- pardes-gui") + +A desktop launcher that still starts pardes without 9ns or `/dev/fuse` +(absolute paths: the `Exec=` line takes a `$` only escaped, and a desktop `PATH` may +lack `~/.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 +``` + +Or let every interactive shell wrap itself, once. fish, in `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 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`, `crontab -e` and fish's `edit_command_buffer` (Alt-E) read +`VISUAL` before `EDITOR`, so set both. + += A pager <pager> + +#cmd("ls --color=always | pardes - # into a new +Pager there, colours kept") + +With #word("Pager") `pardes` (the default) a terminal's shell gets +`PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to it (and +`SYSTEMD_PAGERSECURE=0`) wherever your environment leaves them unset, so +`git log`, `journalctl` and `man` arrive as a pane, a diff drawn as one; +command panes page through `cat`. `man` reads `MANPAGER` first, which +pardes never sets. #word("Pager") `off` in the startup file leaves them all +yours, for terminals started after it; #word("PagerColor") `off` makes the +text plain. + += yazi in a terminal pane <yazi> + +In `~/.config/yazi/yazi.toml` (yazi 26), an opener that forwards files to +the session as panes: + +``` +[opener] +pardes = [ + { run = 'pardes %s', desc = "Open in pardes", for = "unix" }, +] + +[open] +prepend_rules = [ + { mime = "text/*", use = "pardes" }, +] +``` + +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 and PATH <shells> + +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 for a file it knows, from `PATH`: + +#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` (`PARDES_LSP_PY`)], +) + +#cmd("PARDES_LSP_ZIG=$HOME/src/zls/zig-out/bin/zls pardes # another zls\nPARDES_LSP_PY= pardes # none for .py") + +#word("Lspinfo") (#key("SPC l i")) says what is running. + += Fonts and themes <fonts-and-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`; #word("Font") +`Iosevka:16` picks one. #word("Theme") `<name>` and #word("ThemeFile") are in the themes +chapter (#doc("themes")). + += plan9port <plan9port> + +Without a mount, plan9port's `9p` reads and writes a session: + +#cmd("9p -a \"unix!$PARDES_9P\" read index") + +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. |
