From 5e72bfc34cc97d12be5185930135b55c2eb001b4 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 30 Sep 2026 23:04:26 -0300 Subject: The reference is fs.md's per-file semantics, errors and limits in Typst, with the settings table, and says what the pane ctl's Left, Right, Up and Down do Co-Authored-By: Claude Opus 5.5 --- docs/config.md | 202 ------------- docs/fs.md | 763 ------------------------------------------------- docs/macos.md | 4 +- docs/open-questions.md | 4 +- docs/typ/reference.typ | 721 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 725 insertions(+), 969 deletions(-) delete mode 100644 docs/config.md delete mode 100644 docs/fs.md create mode 100644 docs/typ/reference.typ (limited to 'docs') diff --git a/docs/config.md b/docs/config.md deleted file mode 100644 index 23355b06..00000000 --- a/docs/config.md +++ /dev/null @@ -1,202 +0,0 @@ -# Configuration - -## The startup file - -Native builds read one command file, `init`, from the per-user `pardes` -configuration directory: - -- Unix: `$XDG_CONFIG_HOME/pardes/init` (only an absolute `XDG_CONFIG_HOME` - counts), else `~/.config/pardes/init`. -- macOS: `$XDG_CONFIG_HOME/pardes/init` when set, else - `~/Library/Application Support/pardes/init`. -- Windows: `%LOCALAPPDATA%\pardes\init`, else - `%USERPROFILE%\AppData\Local\pardes\init`. - -The browser build has none. A file over 1 MiB or unreadable counts as absent. - -Each line is one builtin, spelled as it would be executed in pardes: - -```text -Theme orchard -Font DejaVuSansMono-Regular -TaglineSize 82 -Shell zsh -Wrap -``` - -A builtin that takes no argument matches only as the whole line (`Kill` runs, -`Kill something` does not); one that takes an argument takes the rest of the -line. Blank, unknown, malformed or failing lines are ignored silently and do -not stop later ones. Text that is no builtin is not run as a shell command -(`Exec ...` still is). Key bindings are compile-time choices in -`src/config.zig`; `init` does not remap them. - -`Config` (`SPC f c`) opens `init` itself in a pane, or goes to its pane when -it is open. With no file there yet, the pane is named for it, empty, and -Save writes it, making its directory first. `DumpConfig` opens a -`+DumpConfig` pane with every live setting, each line the word that sets -it and its value (`Shell /bin/bash`, `PanelSlide off`, `LocationsConfig …`) -and a `# Lift unsupported` comment for one the frontend cannot show. After a blank line -come what is in effect but set by no word, such as the last shell spawned -and the font in use, and the startup path (a right click opens it), each a -`#` line. A line starting with `#` is a comment wherever a line runs (the -init file, a ctl, an exec), so the report can be written back as is. The -root `ctl` file reads the settings back in the words a write takes -([fs.md](fs.md#the-root-ctl)). - -## Settings - -A setting that chooses among words (`on`/`off` switches, `Placement`, -`BootShell`, `Crt`, `Bloom`, `Vignette`, `Grain`, `Lift`, `Motion`, -`ShaderAnimation`) steps to its next value when given bare, as its word -clicked in a tag does; a value it does not take is refused, naming those it -does. `/commands` lists every builtin and its values. - -| setting | default | | -|---|---|---| -| `Theme ` | `orchard` | names as `Themes` (`SPC t t`) lists them ([themes.md](themes.md)); `NextColor` walks the ring | -| `ThemeFile ` | | a `.zon` theme, relative to the config directory; reloads live when saved | -| `FocusTint` | on | tint the focused pane's and column's tags | -| `SyntaxBold` | off | bold syntax keywords | -| `Verbose` | on | a builtin announces its name on the message row | -| `MessageAnimation` | on | messages ease in and dissolve | -| `MessageLinger`, `MessageFall`, `MessageDissolve` | 800, 180, 150 | milliseconds, at most 60000 | -| `Placement acme\|pardes` | `acme` | where new panes go ([tags.md](tags.md#where-new-panes-go)) | -| `BootShell keep\|replace` | `keep` | `replace` closes the untouched lone shell a dragged document lands beside | -| `LookWord search\|list` | `search` | a looked-at word selects its next place, or lists all in `+Search` | -| `Shell ` | `$SHELL`, else the login shell, else `/bin/sh` | the shell the next terminal runs; a bare name is looked for in the usual bin directories, not `$PATH`; bare `Shell` returns to the default | -| `DumpDir ` | `$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes` | where `Dump` writes; `~/` is home; bare returns to the default | -| `TreeContext` | off | sticky declaration headers in a source pane (per pane, dumped) | -| `TreeContextTagStyle` | on | draw those headers in the tagline style | -| `LocationsConfig ...` | | Search, Grep and LSP result layout (below) | -| `Wrap`, `Colors`, `Tagbottom`, `Debug` | | toggles | -| `Font [:]`, `Fonts` | | SDL and macOS only; size 8-72 (pixels in SDL, points on macOS) | -| `TaglineSize <1-100>` | 82 | tagline face, percent; SDL and macOS | -| `WindowOpacity <0-100>` | 100 | SDL only: everything but text and the cursor | -| `Ligatures` | on | SDL only; macOS draws CoreText's own | -| `Pet cat\|frog\|off` | off | SDL only: a sprite in the workspace tag's blank space | - -`Tty9p` (`SPC n 9`) is described in [v9fs.md](v9fs.md); the -`PARDES_V9FS_HELPER` variable points development builds at the helper. - -### Terminals - -Ctrl-B switches a terminal between raw input and editor mode. Plain Escape -at a detected shell prompt hops back to the previous pane; other keys, -Ctrl-O, Ctrl-W and modified Escape included, go to the program. `Mode` in the -tag returns to editor mode in place. Ctrl-V types the yank register and -Ctrl-Shift-V the desktop clipboard, through bracketed paste when the program -asked for it; neither reaches the program as a keystroke. - -`Filter` in a terminal's tag maps its ANSI colours through the theme, -keeping each foreground at least `tty_filter_min_contrast` (WCAG 1.5, in -`src/config.zig`) against its background. - -### Location results - -`LocationsConfig` with no argument prints the current settings as a line -that can be run again; with fields it changes only those: - -```text -LocationsConfig context:5 tscontext:on tslocations:off layout:stacked -``` - -- `context` (0): source lines shown above and below each match. -- `tscontext` (off): include the enclosing tree-sitter declaration headers. -- `tslocations` (on): show a location on each declaration header. -- `layout` (`stacked`): the location on its own line; `inline` puts it - beside the source, padded in groups of eight matches. - -An invalid field rejects the whole line; a repeated field's last value wins. -The settings survive Dump and Restore. Source analysis is cached for 64 -files and 64 MiB. - -### Effects - -Panel transitions, one at a time; running the active one again turns it -off: `PanelSlide`, `PanelZoom`, `PanelDissolve`, `PanelAscii`, -`PanelVertical`, `PanelEdges`, `PanelFall`, `PanelWave`, `PanelCurtain`, -`PanelScramble`, `PanelType`. All start off; the web shell has none. - -Scene passes (SDL GUI, and a GUI attached to a detached session), each at a -level 0-3 (`on` is 2), all off by default: `Crt`, `Bloom`, `Vignette`, -`Grain`. `Shader ` adds a Shadertoy file written for ghostty to -the chain (`Shader off` removes it; it recompiles when saved); -`ShaderAnimation off|on|always` says when the chain animates by itself. - -The focused pane can stand off the page: `Lift shadow|rim|auto|off`, -`InactiveDim `, `Motion off|crisp|smooth|bouncy|playful` -(default `smooth`), `SelectionGlow`, `HoverGlow`, `Occlusion`, `Parallax`, -`JumpTrail`, `ChipShadow`, `ThumbFlash`, `CursorBlink`, `GripWidth <50-300>`. -Most are GUI-only; `InactiveDim` works everywhere, and `JumpTrail`, -`ChipShadow` and `ThumbFlash` are the terminal's. No effect may lower the -contrast of text, the selection or a focus indicator -([effects.md](effects.md)). - -`EffectCode ` lists that effect's sources under `/virtual` when the -build embeds them (`-Dembed-sources=true`). `zig build shaders` refreshes -the committed SPIR-V with its GLSL. - -### Look preview - -Resting the pointer on text for about 32 ms (`look_preview_delay_frames`, 2 -frames) tints what a right click would look at, with no other effect. Set -`look_preview_delay_frames` to `null` in `src/config.zig` to turn it off. - -## Themes from files - -`ThemeFile themes/mine.zon` loads a complete theme; a malformed save keeps -the last good one, and `Theme ` stops the watch. `DumpThemes` writes -every compiled theme to `/themes/builtin/.zon`: copy one, -change its `.name`, and edit. The format is `pardes.Theme` as -`std.zon.stringify` writes it; [themes.md](themes.md) describes each role. - -## Dumps - -`Dump` writes `pardes--