diff options
| author | user <user@clank> | 2026-08-27 16:04:37 +0200 |
|---|---|---|
| committer | user <user@clank> | 2026-08-27 16:04:37 +0200 |
| commit | 5151e42f22b404cf41dc8b409bcdfcd4b39444ea (patch) | |
| tree | da8424903e12bf41a6144b065e06529df4f8e947 /docs/config.md | |
| parent | docs: the landing page stops arguing (diff) | |
| download | slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.tar.gz slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.tar.xz slosh-5151e42f22b404cf41dc8b409bcdfcd4b39444ea.zip | |
README/docs: spell the dash --, as the rest of the tree does
Every C comment, commit message and generated config in this repo
writes the aside dash as a spaced double hyphen; the Markdown alone
used U+2014, some 220 of them. One spelling, and the ASCII one -- the
prose now matches the code it documents.
Mechanical (every occurrence was the spaced form, checked including
the one inside a code fence, where it was comment text), so the words
themselves are untouched.
Diffstat (limited to 'docs/config.md')
| -rw-r--r-- | docs/config.md | 58 |
1 files changed, 29 insertions, 29 deletions
diff --git a/docs/config.md b/docs/config.md index 82e91bc..a59e8e6 100644 --- a/docs/config.md +++ b/docs/config.md @@ -11,25 +11,25 @@ $SLOSH_CONFIG, else $XDG_CONFIG_HOME/slosh/config.kdl, else **Saving it applies to every running session immediately.** A file that will not parse is refused rather than half-applied, and the running config stays. Anything -smaller than that — an unknown shader, a binding that does not parse, an -[`include`](#include) that is not there — applies the rest of the file and says +smaller than that -- an unknown shader, a binding that does not parse, an +[`include`](#include) that is not there -- applies the rest of the file and says which line it could not honour. Three things are read later than the rest, because of *when* they are needed: -`shell` and the two `scrollback` limits apply to the next pane you open — +`shell` and the two `scrollback` limits apply to the next pane you open -- shrinking a pane's history retroactively would throw away output somebody is -reading — and a shader plugin that replaced one already loaded needs a new +reading -- and a shader plugin that replaced one already loaded needs a new session. ## Two files worth knowing -- **`slosh --dump-config`** writes every setting with its *default* value — +- **`slosh --dump-config`** writes every setting with its *default* value -- not the value your config gives it. It is generated from the code, so it cannot drift, and it is a supported way to start a config: `slosh --dump-config > ~/.config/slosh/config.kdl`. To see what your own file does, `slosh --check` reads it and reports what it understood. - **`config/config.kdl`** - in the source tree is the same list with the *reasoning* attached — what each + in the source tree is the same list with the *reasoning* attached -- what each setting is for, what it cost to get right, and which ones are opinions. When the two disagree, the dump is right and that file is stale (a test says so). @@ -40,7 +40,7 @@ $ slosh --check # the config a session would read $ slosh --check themes/mine.kdl # or one you have not installed yet ``` -Every problem it found, one per line, with the file and line it happened at — +Every problem it found, one per line, with the file and line it happened at -- including a setting it does not know: ``` @@ -55,13 +55,13 @@ including a setting it does not know: The problems go to stderr and the summary with them. It exits 1 when it has anything to say, so it drops into an editor's compile -step or a pre-commit hook with no glue. A clean run prints what it read — the -files, the prefix it ended up with, how many bindings — because otherwise a +step or a pre-commit hook with no glue. A clean run prints what it read -- the +files, the prefix it ended up with, how many bindings -- because otherwise a config that was never opened and a config with nothing wrong look identical. It is the loader, not a second implementation of it: the only checker that cannot drift from what a session does is the one a session uses. The single -difference is how many problems each reports — a session has one status line and +difference is how many problems each reports -- a session has one status line and shows the first, and a linter that stopped at the first mistake would make you run it once per mistake. @@ -90,13 +90,13 @@ here, so the same line composes keys, shader chains, states or geometry. ## Themes -Every colour the compositor draws has its own name under `theme { }` — 48 of +Every colour the compositor draws has its own name under `theme { }` -- 48 of them, because six names doing thirty jobs meant the split guide could not be recoloured without also recolouring the focused frame. Six ready-made themes are in `contrib/themes`: -`amber`, `mono`, `paper`, `phosphor`, `sl0p`, `slate` — plus `default`, the +`amber`, `mono`, `paper`, `phosphor`, `sl0p`, `slate` -- plus `default`, the compiled-in palette written out, so another theme is one include-swap away from coming back. Include one and put your own two lines on top: @@ -114,18 +114,18 @@ theme { frame_focus "#00ff88" } // ...but that one colour is mine | geometry | `gap` `gap_aspect` `padding` `compact` `rounded` `title_align` `title_inset` `min_pane` `min_split` | | chrome | `status_bar` `status_line` `status_pad` `hints` `version_banner` `pane_buttons` `bell_indicator` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark`) | | behaviour | `focus_follows_mouse` `scroll_lines` `scrollback` `scrollback_bytes` `toast_ms` `splash_ms` `hover_delay_ms` `double_click_ms` `word_separators` `anim_ms` `modal_scrim` `dim_unfocused` `float_shadow` `keep_dead` `in_band_shaders` `shell` `editor` `shader_dir` | -| projects | `project_roots` `project_layout` — see [workspaces](workspaces.md) | +| projects | `project_roots` `project_layout` -- see [workspaces](workspaces.md) | | colour | `theme { }` | -| effects | `shaders { }`, `states { }` — see [shaders](shaders.md) and [chrome](chrome.md) | -| keys | `keys { }` — see [keys](keys.md) | +| effects | `shaders { }`, `states { }` -- see [shaders](shaders.md) and [chrome](chrome.md) | +| keys | `keys { }` -- see [keys](keys.md) | A few of those take more than one value. `gap` is in **rows**, and `gap_aspect` says how many columns a row is worth (2 by default, because a cell is about -twice as tall as it is wide) — so both `gap` and `padding` are written in rows +twice as tall as it is wide) -- so both `gap` and `padding` are written in rows and come out looking square. `min_pane cols=24 rows=6` and `min_split cols=32 rows=8` name their two floors as properties (what each floor *means* is on the [panes page](panes.md#small-terminals)), and `project_roots` -takes one path per argument — see [workspaces](workspaces.md). +takes one path per argument -- see [workspaces](workspaces.md). `padding` is the space between a pane's frame and its contents, written the way CSS does it: @@ -138,7 +138,7 @@ padding 2 0 0 1 // top, right, bottom, left A number means the same thing however many of them you write, so `padding 1`, `padding 1 1` and `padding 1 1 1 1` are one padding rather than three. Three -values is refused — CSS reads it as top/horizontal/bottom, and a line whose +values is refused -- CSS reads it as top/horizontal/bottom, and a line whose meaning you have to look up is a line nobody can read. ## Compact @@ -148,7 +148,7 @@ compact true ``` Shared borders instead of gaps. Panes pack flush against 1-cell divider lines -that meet in real junctions — `├` `┬` `┼` — one frame rings the whole tab, and +that meet in real junctions -- `├` `┬` `┼` -- one frame rings the whole tab, and each pane's title rides the line above it, so a boundary costs one cell where the default look spends four columns (a border, a two-column gap, a border) or three rows: @@ -163,20 +163,20 @@ three rows: What changes, and what does not: -- `gap` stops applying — the boundary *is* the divider. `padding` still works +- `gap` stops applying -- the boundary *is* the divider. `padding` still works (still aspect-corrected, so `gap_aspect` keeps that job, along with shaping the keyboard's float moves), and `rounded` still picks the corners. - **Dividers drag exactly as gaps did**, corners included, and the same hover hints appear on them. A pane whose title line is a shared divider is still - dragged — by its name. + dragged -- by its name. - **Interior edges give up click-to-split**: a one-cell line cannot honestly hold both verbs, and the whole line is the resize handle. The outer frame keeps its split handles, and the keyboard splits anything, as ever. -- A pane's **status row** — a dead pane's epitaph and its `[re-run] [close]`, - a program's own OSC 5577 row — overlays the pane's last content row, there +- A pane's **status row** -- a dead pane's epitaph and its `[re-run] [close]`, + a program's own OSC 5577 row -- overlays the pane's last content row, there being no bottom border left to carry it. - **Floats keep the classic frame** (an overlay needs its own edge), and so - does a zoomed pane or a flattened tab — nothing there is packed against + does a zoomed pane or a flattened tab -- nothing there is packed against anything. - Chrome shaders run over the pane's stretch of the shared lines; a line between two panes belongs to both, which is what sharing means. @@ -189,14 +189,14 @@ scrollback_bytes 16777216 // ...and the ceiling that count runs into ``` **The default was a library's, not a decision.** lib-vt is handed no limit and -picks its own — 10,000 *bytes*, which measures at 622 lines of an 80-column pane, +picks its own -- 10,000 *bytes*, which measures at 622 lines of an 80-column pane, less than one `make` run. `scrollback` is that number replaced with the one every other multiplexer settled on. The two limits work together because either can be reached first and neither can see what the other depends on: a line count cannot know how wide your terminal is or how many styles a program used, and a byte count cannot know how many lines -that bought. Whichever bites first wins. Both are estimates — history is pruned a +that bought. Whichever bites first wins. Both are estimates -- history is pruned a page at a time (a page is about 400KB of grid), so a pane keeps a little more than it was told, never less. @@ -210,7 +210,7 @@ What the ceiling costs, measured on a pane filled with styled output: So it is invisible at ordinary widths and a brake at extraordinary ones, which is its job. It is per **pane**: sixty panes full of history is sixty times it, which -is why there is no `unlimited` — at that many panes it would be a memory leak with +is why there is no `unlimited` -- at that many panes it would be a memory leak with a friendly name. `scrollback_bytes 0` removes the ceiling if you have one very wide pane and want every line of it. @@ -243,7 +243,7 @@ states { // ...and the whole table underneath it ``` The full ranking, most urgent first: `dragging`, `drop_hover`, `drop_target`, -`dead`, `suspended`, `bell`, `scrolled`, `floating`, `unfocused`. Exactly one wins — the -first that matches — because two reasons to be grey compound into one muddy grey +`dead`, `suspended`, `bell`, `scrolled`, `floating`, `unfocused`. Exactly one wins -- the +first that matches -- because two reasons to be grey compound into one muddy grey that reads as neither. Naming a state replaces its default outright, including with nothing, which is how you turn one off. |
