summaryrefslogtreecommitdiff
path: root/docs/typ/setup.typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ/setup.typ')
-rw-r--r--docs/typ/setup.typ136
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.