aboutsummaryrefslogtreecommitdiffstats
path: root/docs/layouts.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-27 16:04:37 +0200
committeruser <user@clank>2026-08-27 16:04:37 +0200
commit5151e42f22b404cf41dc8b409bcdfcd4b39444ea (patch)
treeda8424903e12bf41a6144b065e06529df4f8e947 /docs/layouts.md
parentdocs: the landing page stops arguing (diff)
downloadslosh-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/layouts.md')
-rw-r--r--docs/layouts.md72
1 files changed, 36 insertions, 36 deletions
diff --git a/docs/layouts.md b/docs/layouts.md
index cdb57a0..20d555d 100644
--- a/docs/layouts.md
+++ b/docs/layouts.md
@@ -21,14 +21,14 @@ slosh --layout project.layout
## What to call them
-**`*.layout`** — a project's is `slosh.layout`. The syntax is still the same
+**`*.layout`** -- a project's is `slosh.layout`. The syntax is still the same
KDL subset the config uses, one parser reads both files, and for a while the
files were `*.layout.kdl` on the argument that the extension should say so.
The argument lost to a collision: zellij speaks the same syntax under that
same extension with a different schema, and to anyone arriving from there
-`.kdl` said *whose* file it is — naming the wrong owner is worse than not
+`.kdl` said *whose* file it is -- naming the wrong owner is worse than not
naming the parser. The name says what the file is; `slosh --check` says how
-it was read. (Point your editor's KDL highlighting at `*.layout` — it *is*
+it was read. (Point your editor's KDL highlighting at `*.layout` -- it *is*
still KDL underneath.) The old spelling is still found by the project scan,
never written.
@@ -38,8 +38,8 @@ it: a file with `layout` or `tab` at the top of it is checked as a layout, and a
config handed to the same flag is still checked as a config. A file too broken to
parse at all is judged by its name, because by then there is nothing else left to
read. One flag rather than a `--check-layout` beside it: naming the schema is the
-part you wanted the checker to do, and the answer it used to give — `this is a
-layout, not a config` — replied to a question about a file with the name of
+part you wanted the checker to do, and the answer it used to give -- `this is a
+layout, not a config` -- replied to a question about a file with the name of
another flag.
```
@@ -50,7 +50,7 @@ project.layout: ok, a layout
A clean layout says which schema it passed, because otherwise a layout nothing
could open and a layout with nothing wrong in it read the same. A broken one
reports every problem it found, one indented `file:line: what` per line, then a
-summary, and exits 1 — the shape [checking a config](config.md#checking-one)
+summary, and exits 1 -- the shape [checking a config](config.md#checking-one)
already has, so one editor compile step and one pre-commit hook read both:
```
@@ -67,7 +67,7 @@ broken.layout: 6 problems
Those are the mistakes a layout can make that still parses: a property no pane
has, a `split=` that is neither direction, a `weight=` that is not a number the
engine will honour, a `true`/`false` written some other way, a `purpose=` on a
-split — which would tag nothing, because a split runs nothing — and a child node
+split -- which would tag nothing, because a split runs nothing -- and a child node
that is not a `pane`. Last comes `this layout declares no tabs`, reported at the
end rather than first so it reads as the summary it is.
@@ -85,29 +85,29 @@ which file is which.
## The shape
-- `tab` — one per tab, in strip order. `name=`, `cwd=`, `purpose=`,
+- `tab` -- one per tab, in strip order. `name=`, `cwd=`, `purpose=`,
`active=true` for the one you land in.
-- `pane` — a leaf, or a split when it has `pane` children. `split="cols"|"rows"`
+- `pane` -- a leaf, or a split when it has `pane` children. `split="cols"|"rows"`
says which way it divides; `weight=` is its share of the parent (even shares
are equal weights, so leaving it out means "even").
-- `command=` — what it runs. Without one, a pane runs your shell.
-- `cwd=` — where it starts. Inherited from the tab when the pane does not say.
-- `suspended=true` — laid out but running nothing until you touch it, so twelve
+- `command=` -- what it runs. Without one, a pane runs your shell.
+- `cwd=` -- where it starts. Inherited from the tab when the pane does not say.
+- `suspended=true` -- laid out but running nothing until you touch it, so twelve
checked-out projects are not twelve running dev servers. The pane shows what it
*would* run.
-- `focus=true` — the pane you start in, within its tab.
-- `floating=true` — the pane starts [floating](panes.md#floating-a-pane), with
+- `focus=true` -- the pane you start in, within its tab.
+- `floating=true` -- the pane starts [floating](panes.md#floating-a-pane), with
`x=` `y=` `w=` `h=` as its wanted rect in cells (absent, it takes the centred
default). The rect is intent: a smaller screen clamps it, and the place you
- asked for survives. It still holds a seat in the tree — its `weight=` and
+ asked for survives. It still holds a seat in the tree -- its `weight=` and
position are where un-floating lands it. A file whose every pane floats
lands one as the backdrop, because an overlay needs something to be over.
-- `purpose=` — a label for tooling; see below.
+- `purpose=` -- a label for tooling; see below.
**A relative `cwd=` in a layout *file* resolves against that file's own
directory**, never against the directory you started the session from. It is the
rule [`include`](config.md#include) already follows for configs, applied to the
-other half of the same syntax — the two documents share a parser, so they should
+other half of the same syntax -- the two documents share a parser, so they should
not disagree about what a relative path is. A layout with no `cwd=` anywhere
starts in the file's directory too, so the common case needs no `cwd=` at all. An
absolute path is unchanged, and `~` is still your home directory.
@@ -116,7 +116,7 @@ That is what lets a layout be checked in beside the project it describes and mea
the same thing in everybody's clone:
```kdl
-// ~/dev/api/slosh.layout — no absolute path in it anywhere
+// ~/dev/api/slosh.layout -- no absolute path in it anywhere
layout {
tab name="api" cwd="." {
pane command="nvim"
@@ -129,8 +129,8 @@ layout {
```
Clone that repo somewhere else and the tab still opens on the checkout, with the
-pane that said `src` still in the checkout's `src`. The alternative — absolute
-paths, or a `$PROJECT` of our own to expand — makes the file personal to one
+pane that said `src` still in the checkout's `src`. The alternative -- absolute
+paths, or a `$PROJECT` of our own to expand -- makes the file personal to one
machine, or makes you learn a variable to say "here".
A layout that arrives as *text* over the socket has no file, and so no directory
@@ -154,27 +154,27 @@ after a restart.
is that loop, for when the thing you are rebuilding is slosh itself.
**A pane is dumped with the command it is running**, whether a layout gave it one
-or you typed it. `label` — what a layout said — comes first and outlives the
+or you typed it. `label` -- what a layout said -- comes first and outlives the
program that ran it, so a project's `command="npm run dev"` stays that in the file
after the server has exited. Failing that, the pane's terminal is asked what owns
it: a pty has a foreground process group, and that group *is* the job running in
the pane. So arranging a project by hand and writing it down are one job rather
-than two — split, start the dev server and the log tailer, `C-a W`, done.
+than two -- split, start the dev server and the log tailer, `C-a W`, done.
Three things are deliberately not a command. **A shell at a prompt**, because
`command="zsh"` on every idle pane would restore a session where each shell runs
inside a shell. **A background job**, because it does not own the terminal and a
layout that resurrected `&` jobs in the foreground would describe a session nobody
-had. And **an [ephemeral](panes.md#panes-that-were-given-a-command) pane** — the
-editor `C-a e` opened — because restoring one reopens a file somebody finished
+had. And **an [ephemeral](panes.md#panes-that-were-given-a-command) pane** -- the
+editor `C-a e` opened -- because restoring one reopens a file somebody finished
with.
Argv is joined with shell quoting, since `command=` is handed to `/bin/sh -c`:
`python3 -c 'import x; x.go()'` comes back as one argument rather than three.
What a dump can honestly restore is the *shape*, and the command that made it.
-What it cannot is the state inside a program — a shell's history, a half-written
-commit message, an editor's undo — and it does not pretend otherwise. A pane
+What it cannot is the state inside a program -- a shell's history, a half-written
+commit message, an editor's undo -- and it does not pretend otherwise. A pane
running the session's default shell is dumped as a pane with no command, so
restoring gives you a fresh one.
@@ -198,7 +198,7 @@ afterwards. `suspend` takes four words:
| word | means |
|---|---|
-| `as-is` | what is suspended in the session right now — the default here, because a session dump should describe the session |
+| `as-is` | what is suspended in the session right now -- the default here, because a session dump should describe the session |
| `none` | everything comes back running |
| `commands` | every pane that was given a command |
| `all` | nothing starts until you touch it |
@@ -207,8 +207,8 @@ afterwards. `suspend` takes four words:
[workspaces](workspaces.md) saves with: the pane running this morning's dev server
belongs in the file asleep, or opening the project starts a dev server every time.
-The reply carries the document as `kdl` and counts beside it — `panes` and
-`suspended` — so a caller can report "4 panes, 2 suspended" without parsing back
+The reply carries the document as `kdl` and counts beside it -- `panes` and
+`suspended` -- so a caller can report "4 panes, 2 suspended" without parsing back
the document it was handed. A `tab` that does not exist is an error rather than an
empty document, because an empty layout is a plausible answer for a tab you closed
a minute ago and a silent one for a typo in an id.
@@ -236,7 +236,7 @@ slosh cmd '{"cmd":"move-pane","id":3,"tab":2,"dir":"rows"}' # under it instead
slosh cmd '{"cmd":"move-pane","id":3,"tab":0,"name":"logs"}' # into a tab of its own
```
-The pane keeps running: same pty, same scrollback, same process — a move is tree
+The pane keeps running: same pty, same scrollback, same process -- a move is tree
surgery, not a new pane and a funeral. The destination is a tab **id** rather than
an index, because a tab whose last pane leaves is removed and every index after it
shifts; an id survives that.
@@ -247,18 +247,18 @@ first would zoom a pane that has left and the second would file the arrival in a
strip nobody asked for. Which tab you are *looking* at does not change.
`C-a >` and `C-a <` push the focused pane one tab along, `C-a b` gives it a tab of
-its own, and a pane can be dragged onto a tab in the strip — see
+its own, and a pane can be dragged onto a tab in the strip -- see
[keys](keys.md#defaults) and [the mouse](panes.md#the-mouse).
## Purposes
-A pane or tab can carry a `purpose=` label — `agent:main`, `logs`, `db` — for
+A pane or tab can carry a `purpose=` label -- `agent:main`, `logs`, `db` -- for
tooling to find it by. A purpose declared in a layout or over the control API is
*locked*: a program inside the pane cannot overwrite it, so identity comes from
the layout rather than from whatever the program decides to print.
-`C-a P` gives the focused pane one from the keyboard — see
-[keys](keys.md#defaults) — and **a purpose an operator typed counts as declared,
+`C-a P` gives the focused pane one from the keyboard -- see
+[keys](keys.md#defaults) -- and **a purpose an operator typed counts as declared,
so it locks like one from a file**. The lock is not about which door the label
came through, it is about the label coming from outside the pane at all: you named
that pane `service:web` on purpose, and the shell in it printing a title is not an
@@ -276,8 +276,8 @@ The [finder](panes.md#finding-a-pane) matches on purposes as well as titles, and
## When the layout is found rather than named
-Everything above assumes you name the file. When it lives *in* the project —
-`slosh.layout` beside the `.git` — you do not have to: `C-a w` lists the
+Everything above assumes you name the file. When it lives *in* the project --
+`slosh.layout` beside the `.git` -- you do not have to: `C-a w` lists the
projects under the roots you configured and opening one applies the layout it
found there, or a default layout bound to that directory when the project has
none, and `C-a W` writes this tab back out as that file. Same syntax, same