aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-16 20:23:03 +0200
committeruser <user@clank>2026-08-16 20:23:03 +0200
commit2182ef505c6f12545cf156cca85a629256c28c72 (patch)
tree75a53a5fe4715b65172a33df633dd382e3944528 /docs
parentsl0ppty: docs that match the program (diff)
downloadslosh-2182ef505c6f12545cf156cca85a629256c28c72.tar.gz
slosh-2182ef505c6f12545cf156cca85a629256c28c72.tar.xz
slosh-2182ef505c6f12545cf156cca85a629256c28c72.zip
sl0ppty: layouts are `*.layout.kdl`, and each loader says which it got
`config/layout.example.kdl` becomes `config/example.layout.kdl`, and the convention for the files people write is `project.layout.kdl`. Not a new extension, and the reason matters: the syntax genuinely *is* the same hand-rolled KDL subset for both documents -- one parser reads them -- so calling layouts something other than KDL would trade one wrong signal for another and lose every editor that highlights it. The confusion is about *schema*, so the schema goes in the stem: the extension says how to read the file, `.layout` says what is in it. `docker-compose.yml` and `tsconfig.json` settled this convention long ago. **But a filename cannot enforce anything, and that turned out to be the real bug.** `sl0ppty --check` on a layout file printed `ok` and reported "bindings 53" -- it had read a document containing nothing it understood and said so was fine. A config that `include`d a layout linted clean for the same reason. So did `rouded true`. The loader reads a document by *asking it for the keys it knows*, which is fast and clean and never notices what it was given. So it notices now. `KNOWN_TOP` is every node the loader reads, and anything else at the top level is a complaint with a file and line: s.kdl:2: unknown setting: rouded example.layout.kdl:14: this is a layout, not a config: `sl0ppty --layout` reads those sl0ppty: config.kdl: this is a config, not a layout: `gap` is a setting The `layout` node gets its own message because it is the mistake people actually make, and the reverse direction is the same list read backwards -- the layout loader asks `config_is_setting()` rather than keeping a guess of its own, so the two answers cannot disagree about which file is which. A layout whose own tabs are misspelled still gets "layout declares no tabs", which is a different mistake. D2 records it, since it is the decision that two schemas share one syntax. Verified: `tests/test_config.py` gained thirteen checks -- the unknown setting with its line, both wrong-schema messages, the misspelled-tabs case keeping its own, the shipped config linting clean and the shipped layout loading as one, and a drift guard that greps `kdl_child(root, ...)` out of the loader and fails if a setting is missing from `KNOWN_TOP` (verified by removing `gap_aspect` and watching it fail). Full suite green; my own config and the reference config both still lint clean, which is the thing this change could most easily have broken.
Diffstat (limited to 'docs')
-rw-r--r--docs/config.md13
-rw-r--r--docs/layouts.md28
2 files changed, 32 insertions, 9 deletions
diff --git a/docs/config.md b/docs/config.md
index 0878eed..c42fb01 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -37,15 +37,18 @@ $ sl0ppty --check # the config a session would read
$ sl0ppty --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, and a file that turns out to be a
+[layout](layouts.md#what-to-call-them) rather than a config:
```
cannot open /home/you/.config/sl0ppty/themes/nope.kdl
- config.kdl:12: bad prefix: ctrl+nope
- config.kdl:14: bad key: wobble
- config.kdl:15: unknown action: fly
+ config.kdl:2: bad prefix: ctrl+nope
+ config.kdl:3: bad key: wobble
+ config.kdl:5: padding takes 1, 2 or 4 values (all, vertical horizontal, or top right bottom left), not 3
+ config.kdl:6: unknown setting: wobble
themes/mine.kdl:7: unknown shader: bloom
-~/.config/sl0ppty/config.kdl: 5 problems
+~/.config/sl0ppty/config.kdl: 6 problems
```
The problems go to stderr and the summary with them. It exits 1 when it has
diff --git a/docs/layouts.md b/docs/layouts.md
index 0d4e50c..c228d9e 100644
--- a/docs/layouts.md
+++ b/docs/layouts.md
@@ -16,9 +16,29 @@ layout {
```
```bash
-sl0ppty --layout session.kdl
+sl0ppty --layout project.layout.kdl
```
+## What to call them
+
+**`*.layout.kdl`.** The syntax is the same KDL subset the config uses — one
+parser reads both files — so the extension says how to read it and `.layout`
+says what is in it, the way `docker-compose.yml` and `tsconfig.json` do it.
+Calling it something else would trade one wrong signal for another: it *is*
+KDL, and an editor that highlights KDL is worth keeping.
+
+A filename cannot enforce anything, so the program says which document it got:
+
+```
+$ sl0ppty --check project.layout.kdl
+ project.layout.kdl:8: this is a layout, not a config: `sl0ppty --layout` reads those
+$ sl0ppty --layout ~/.config/sl0ppty/config.kdl
+sl0ppty: config.kdl: this is a config, not a layout: `gap` is a setting
+```
+
+Both come from the same list of settings the loader reads, so the two answers
+cannot disagree about which file is which.
+
## The shape
- `tab` — one per tab, in strip order. `name=`, `cwd=`, `purpose=`,
@@ -35,12 +55,12 @@ sl0ppty --layout session.kdl
- `purpose=` — a label for tooling; see below.
A full annotated example is
-`config/layout.example.kdl`.
+`config/example.layout.kdl`.
## Writing one back out
```bash
-sl0ppty -s work cmd '{"cmd":"dump-layout"}'
+sl0ppty -s work cmd '{"cmd":"dump-layout"}' > project.layout.kdl
```
writes the session as a layout file: tabs, splits, proportions, directories,
@@ -57,7 +77,7 @@ command, so restoring gives you a fresh one.
## Applying one to a running session
```bash
-sl0ppty -s work cmd '{"cmd":"apply-layout","path":"session.kdl"}'
+sl0ppty -s work cmd '{"cmd":"apply-layout","path":"project.layout.kdl"}'
sl0ppty -s work cmd '{"cmd":"apply-layout","kdl":"layout { tab { pane } }","replace":true}'
```