diff options
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. |
