aboutsummaryrefslogtreecommitdiffstats
path: root/docs/keys.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-15 23:53:30 +0200
committeruser <user@clank>2026-08-15 23:53:30 +0200
commit4dc055692c56324a94d1087331da8862ea650d2b (patch)
tree5ddec99f7cf6b144ede4138b6e952c84379725aa /docs/keys.md
parentsl0ppty: marks a font actually draws at cell size (diff)
downloadslosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.gz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.xz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.zip
sl0ppty: a README you can read, and docs/ for the rest
The README was 331 lines and had become a manual with a title. Everything in it was true and most of it was the wrong thing to hand somebody who has just arrived: five pages of shader expression semantics before they have split a pane. So the front page is 60 lines -- what it is, install, run, where the docs are, and six bullets on what is actually different about it -- and the detail moved into docs/, nine pages that each answer one question: index.md what it is, install, run, where to go keys.md the leader, every default, rebinding, direct binds panes.md splitting, resizing, the mouse, dead panes, small terminals config.md the file, live reload, include, themes, the knobs shaders.md the passes, the built-ins, the expression language chrome.md where="chrome", channel, since, the perimeter trick layouts.md a session as a file, and writing one back out scripting.md the control socket, OSC 5577, headless design.md the two decisions, and a map of the source docs/nav holds the order and the grouping and nothing else -- titles come from each page's own heading, so a renamed page cannot end up with two names. It is what the site generator will read. Reference material that only existed in code comments is written down for the first time: every action that can be bound (including the two with no default key, which is what the palette is for), every control verb, the built-in shaders with what each takes, the pane-state ranking, and the layout file's shape. Two things I got wrong on the first pass and fixed before committing: the docs linked repo files through github.com URLs for a project whose remote is a private git server, so those are inline paths now; and the README advertised `make docs`, which does not exist yet. It will in the next commit, and it can be advertised then.
Diffstat (limited to 'docs/keys.md')
-rw-r--r--docs/keys.md95
1 files changed, 95 insertions, 0 deletions
diff --git a/docs/keys.md b/docs/keys.md
new file mode 100644
index 0000000..e421df2
--- /dev/null
+++ b/docs/keys.md
@@ -0,0 +1,95 @@
+# Keys
+
+Everything is the **leader** (`C-a` by default) and then a key. Pressing the
+leader twice sends it to the program in the pane.
+
+`C-a ?` shows a cheatsheet built from the bindings your config actually has, so
+it cannot disagree with your keyboard. `C-a p` opens the same list as a palette
+you can type into.
+
+## Defaults
+
+| key | does |
+|---|---|
+| `\` `-` | split into columns / rows |
+| `h` `j` `k` `l`, or arrows | move focus |
+| `o` | the next pane |
+| `H` `J` `K` `L`, or shift+arrows | move the boundary between panes |
+| `=` | give every visible pane an even share |
+| `Space` | turn the layout a quarter turn (four brings it back) |
+| `z` | zoom this pane to fill the tab, and back |
+| `m` | minimise it into the strip along the bottom |
+| `x` | close this pane |
+| `r` | run a finished pane's command again |
+| `c` | new tab |
+| `Tab` `shift+Tab` | next / previous tab |
+| `1`…`9` | go to that tab |
+| `f` | find a pane by name |
+| `p` | the command palette |
+| `PgUp` `PgDn` `Home` `End` | scrollback (the wheel works too) |
+| `e` | edit the config, in a pane |
+| `?` | this list |
+| `d` | detach, leave it running |
+| `q` | quit the session |
+| `C-a` | send a literal `C-a` |
+
+## Rebinding
+
+`C-a` is a default, not a decision. If you want it back for start-of-line — and
+plenty of people do — one line takes it:
+
+```kdl
+keys { prefix "ctrl+b" } // or ctrl+space, or alt+x, or ...
+```
+
+Everything that names the prefix follows what you bound: the badge in the status
+bar, the cheatsheet's `C-a then:` caption, the palette's key column.
+
+A `keys` block **adds to** the defaults rather than replacing them, so binding
+one key leaves the rest alone. `"none"` takes a binding away:
+
+```kdl
+keys {
+ bind "v" "split-cols" // as well as \
+ bind "-" "none" // and no more splitting into rows
+}
+```
+
+Modifiers are `ctrl+ alt+ shift+ super+`. Named keys are
+`left right up down enter tab escape space backspace home end pageup pagedown
+delete insert backslash minus slash comma period`; anything else is the
+character you press, so `"?"` and `"S-slash"` are the same binding.
+
+## Without the leader
+
+Bindings in a `direct` block fire the moment you press them:
+
+```kdl
+keys {
+ direct {
+ bind "ctrl+alt+left" "focus-left"
+ bind "ctrl+alt+right" "focus-right"
+ }
+}
+```
+
+That chord is then gone from every program in every pane, because it has to be.
+It is a footgun and it is yours; the cheatsheet lists direct bindings apart,
+under "without the leader", so the `C-a then:` caption above stays true.
+
+## Every action
+
+Any of these can be bound, and any of them can be run from the palette without
+being bound at all.
+
+| group | actions |
+|---|---|
+| panes | `split-cols` `split-rows` `close-pane` `rerun` `zoom` `minimize` `rotate-layout` |
+| focus | `focus-left` `focus-right` `focus-up` `focus-down` `focus-next` `finder` |
+| size | `resize-left` `resize-right` `resize-up` `resize-down` `equalize` |
+| tabs | `new-tab` `next-tab` `prev-tab` `select-tab-1` … `select-tab-9` |
+| scroll | `scroll-up` `scroll-down` `scroll-page-up` `scroll-page-down` `scroll-top` `scroll-bottom` |
+| session | `palette` `help` `edit-config` `detach` `quit` `literal-prefix` |
+
+`scroll-up` and `scroll-down` have no default key — the wheel does that job —
+which is exactly the case the palette exists for.