diff options
Diffstat (limited to 'docs/typ/setup.typ')
| -rw-r--r-- | docs/typ/setup.typ | 137 |
1 files changed, 51 insertions, 86 deletions
diff --git a/docs/typ/setup.typ b/docs/typ/setup.typ index 60ea33cd..45767757 100644 --- a/docs/typ/setup.typ +++ b/docs/typ/setup.typ @@ -3,31 +3,22 @@ // 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. +pardes runs as it is; a few lines elsewhere make it fit. = 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: +`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 +as 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`. +A desktop launcher that still starts pardes without 9ns or `/dev/fuse` +(absolute paths: `Exec` takes a `$` only escaped, and a desktop `PATH` may +lack `~/.local/bin`): ``` [Desktop Entry] @@ -35,13 +26,9 @@ 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`: +Or let every interactive shell wrap itself, once. fish, in `config.fish`: ``` if status is-interactive; and not set -q NINE_MOUNT @@ -60,41 +47,33 @@ 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: +`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` (`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`. +`git commit`, `crontab -e` and fish's `edit_command_buffer` (Alt-E) read +`VISUAL` before `EDITOR`, so set both. = A pager <pager> `pardes -` reads its standard input into the directory's one `+Pager` -pane, escapes stripped, and returns; the next paged text refills it. With -`Pager pardes` (the default) a terminal's shell gets `PAGER`, `GIT_PAGER` -and `SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when -it needs it), and `SYSTEMD_PAGERSECURE=0` (it has no shell escape), each -only where your environment does not set it. So `git log`, `journalctl` or -`man` output arrives as a pane to search and click in, a diff (`git diff`, -`git show`, `git log -p`) drawn as one, and the terminal is back at once; -command panes page through `cat`. `man` pages through `MANPAGER` first, -then `PAGER`, and pardes never sets `MANPAGER`: your own `MANPAGER` wins, -as does any `PAGER`, `GIT_PAGER` or `SYSTEMD_PAGER` of yours. To keep your -own pager, set it in your environment, or put `Pager off` in the startup -file (or write it to the root ctl); it applies to terminals started after -it. Outside pardes, `PAGER='pardes -'` opens a new editor on the text. +pane, colours kept, and returns. With `Pager pardes` (the default) a +terminal's shell gets `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to it, +and `SYSTEMD_PAGERSECURE=0`, each only where your environment does not set +it. So `git log`, `journalctl` or `man` output arrives as a pane to search +and click in, a diff drawn as one; command panes page through `cat`. `man` +reads `MANPAGER` first, which pardes never sets. Any pager of your own wins; +`Pager off` in the startup file keeps them all yours, for terminals started +after it. git colours what it pages by default (`color.pager`); ask other +programs for colour outright (`ls --color=always | pardes -`), and put +`PagerColor off` in the init file for plain text. = 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): +In `~/.config/yazi/yazi.toml` (yazi 26), an opener that forwards files to +the session as panes: ``` [opener] @@ -108,30 +87,24 @@ prepend_rules = [ ] ``` -`%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. +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 <shells> += Shells and PATH <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`. +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 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. +pardes starts a language server for a file it knows, finding the program +on `PATH`; `PARDES_LSP_<LANG>` names another, and an empty value turns it +off. #pairs( [`.zig`], [`zls` (`PARDES_LSP_ZIG`)], @@ -139,33 +112,25 @@ program, and an empty value turns that language off. [`.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`)], + [`.py`], [`pyright-langserver --stdio` (`PARDES_LSP_PY`)], ) -#word("Lspinfo") (#key("SPC l i")) says which server serves the file and -what state it is in. +#word("Lspinfo") (#key("SPC l i")) says what is running. = 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")). +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`; `Font +name:size` picks one. `Theme <name>` and `ThemeFile` are in the themes +chapter (#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: +Without a mount, plan9port's `9p` reads and writes a session: #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. +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. |