diff options
| author | user <user@clank> | 2026-08-16 20:23:03 +0200 |
|---|---|---|
| committer | user <user@clank> | 2026-08-16 20:23:03 +0200 |
| commit | 2182ef505c6f12545cf156cca85a629256c28c72 (patch) | |
| tree | 75a53a5fe4715b65172a33df633dd382e3944528 /docs | |
| parent | sl0ppty: docs that match the program (diff) | |
| download | slosh-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.md | 13 | ||||
| -rw-r--r-- | docs/layouts.md | 28 |
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}' ``` |
