summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/helix-keys.md4
-rw-r--r--docs/next-winmode.md69
-rw-r--r--docs/typ/builtins-gui.json2
-rw-r--r--docs/typ/builtins-tty.json2
-rw-r--r--docs/typ/cheatsheet.typ4
-rw-r--r--docs/typ/guide.typ7
-rw-r--r--docs/typ/reference.typ6
7 files changed, 84 insertions, 10 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md
index fa06c9a6..d47f3051 100644
--- a/docs/helix-keys.md
+++ b/docs/helix-keys.md
@@ -128,7 +128,7 @@ language-backend queries, and the shell pipe.
| `Tab` (normal) | acme **execute** chord | pardes-specific, keep; explicit-selection rule as Enter | pardes-specific |
| `:` (normal, body or tag) | in the body, focuses the pane's tag in normal mode at its remembered cursor (the first time, on `Save`); in the tag, goes back to the body; in a column or workspace tag, back to the active pane. The tag's normal and insert modes ARE the body's: every motion, selection, edit and undo works there, and `0` goes to the line's start, the path's. Tab runs the word under the cursor or the selection and Enter looks it up (in a column or workspace tag Enter runs it too), and either hands the keyboard back to the body first. Clicks choose a new cursor position and type into the tag. | Each tag keeps its own cursor during the session. The computed path/marker/page is reachable and yankable but read-only: an edit into it is refused, and typing into a file's path drafts a new name. File-name changes are staged as described in [editable tags](typ/guide.typ). | pardes-specific |
| `Ctrl-w k` / `SPC w k` (window mode, pane with nothing above) | focuses its column's tag, then the workspace tag. `Ctrl-w j` walks back to the panes, `Ctrl-w h`/`l` walk the column tags. Headers edit exactly as a pane tag does. | Column commands target that column's active pane, or its first pane when coming from elsewhere. Workspace and column text are independently editable and persist in dumps. See [editable tags](typ/guide.typ). | pardes-specific |
-| `Ctrl-w` / `SPC w`, then `h/j/k/l`/arrows | window mode (`Window`): an outline moves between panes, `Enter`/`Esc` focuses it, a pane's label letter focuses that pane — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). On a header `Ctrl-w` stays a prefix for the `Left`/`Down`/`Up`/`Right` header walk; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific |
+| `Ctrl-w` / `SPC w`, then `h/j/k/l`/arrows, `d`, `c` | window mode (`Window`): an outline moves between panes, `Enter`/`Esc` focuses it, a pane's label letter focuses that pane, `d` is `Del` on the outlined pane (its `k`/`j` answer between two panes, the outline moving to the pane that took the rows), `c` is `Collapse`; the mode stays on — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). On a header `Ctrl-w` stays a prefix for the `Left`/`Down`/`Up`/`Right` header walk; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific |
| `Alt-n` | new terminal below (outside raw tty) | shadows helix `Alt-n` (select next sibling), which pardes spells `Alt-right` alone | pardes-specific |
| `Alt-c` | move active terminal to a fresh column (outside raw tty) | helix `Alt-c` is change-noyank; the pardes window op wins (do-not-touch contract). `Alt-d` + `i` covers the behavior | waived (`alt-c-window-op`) |
| `Space` (normal, body) | starts the pardes LEADER: a key path runs the same builtin words used by tags and the topbar. The main groups are `f` files, `h` docs, `c` columns, `t` toggles/effects, `a` panel animations, `s` session, `j` jumps, `l` language, and `w` directional focus; `SPC ?` lists every path and `<prefix> ?` lists one group in `+Help`. Neither `Exit` (quits the editor, acme's Exit) nor `Kill` (stops the commands pardes typed into terminals, acme's Kill) has a leader path: both are the topbar's and the root `ctl`'s. The pending path appears on the active pane's transient body/message row. Esc or an unmapped key abandons it. Paths, Help rows, and dispatch are all generated from the builtin registry at comptime; the leader applies only to a BODY in normal mode because tags and tty programs own their input | pardes-specific; helix spends Space on pickers/LSP (section C), while pardes uses acme-style executable words |
@@ -358,7 +358,7 @@ text.
| Popup `Ctrl-u`/`Ctrl-d`, Completion menu, Signature help tables | LSP popups | LSP |
| Picker table (all rows), Prompt table (all rows) | picker / prompt internals | pickers — pardes' tag line is its own one-line editor |
| `gn` `gp` `ga` `gm` | next/prev/alternate buffer | buffer nav — pardes panes aren't a buffer list |
-| Window mode table: `Ctrl-w` + `w v s t f F h j k l q o H J K L ns nv` (+ Ctrl variants) | splits/window management | window mode — pardes has its own Ctrl-w focus + Alt-n/Alt-c + mouse layout drags |
+| Window mode table: `Ctrl-w` + `w v s t f F h j k l q o H J K L ns nv` (+ Ctrl variants) | splits/window management | window mode — pardes has its own Ctrl-w focus + Alt-n/Alt-c + mouse layout drags; of helix's table it keeps `h j k l`, and closes with `d` (`Del`, which asks `k`/`j`) where helix has `q`, `c` collapsing |
| `]g [g ]G [G` | git change jumps | **deferred by decision**: needs a diff base per file (jj `@-` or git HEAD, fetched by the host on open and save) and line hunks from diffz; the design is written up, the work waits |
| insert `Ctrl-x` | completion menu | completion exists, but not as a popup: insert-mode Tab straight after a `.` opens a buffer of candidate DECLARATIONS (section A). helix's menu itself is skipped |
| `Ctrl-s` (normal) | save jumplist position | jumplist itself is implemented (`Ctrl-o`/`Ctrl-i`, section A); only the explicit save point is skipped |
diff --git a/docs/next-winmode.md b/docs/next-winmode.md
new file mode 100644
index 00000000..c2a01da8
--- /dev/null
+++ b/docs/next-winmode.md
@@ -0,0 +1,69 @@
+# winmode: d and c in window mode, the Del question as a hint
+
+> The window mode should have d for deleting and c for collapsing too, the
+> deletion should keep that j/k movement. The current spc d j/k should only
+> show the message after a timeout so that a user that does this fast won't
+> even see it, it will be more like a hint for users that tried to delete
+> and nothing happenend.
+
+## As built
+
+- `layout.windowKey`: `c` runs `Collapse` on the outlined pane; `d` makes
+ the outlined pane active and runs `Del` on it, exactly the keyboard Del
+ (`can_ask` is set: it is a key). With panes above and below, Del asks
+ and the next key is its answer (`Pardes.answerQuestion`, which already
+ runs before window mode sees keys); with one neighbour it closes at once.
+ Either way, once the pane is gone the outline moves to `p.active`, which
+ `removePane` already sets to the pane that grew into the rows. The mode
+ stays on: `Ctrl-w d j d` closes two panes. A refused Del (unsaved text)
+ leaves the outline where it is, the refusal on the message row.
+- Keys: `config.window_delete` (`d`) and `config.window_collapse` (`c`),
+ apart from `window_keys`, because those are also the header walk under
+ `Ctrl-w` on a tag, where `d`/`c` mean nothing.
+- Labels: `layout.window_labels` loses `d` and `c` (22 -> 20 letters).
+- The hint: Del sets `Pane.question_due_ns = clock + 400 ms` when it asks;
+ `Messages.collectNotices` leaves the prompt band out while
+ `question_due_ns > now_ns`; `nextWake` wakes once at that time (while
+ `question_due_ns > stepped_ns`, so stepping past it ends the wake and a
+ tick draws the frame). Same pattern as the REPL's `repl_enter_due_ns`.
+ The question exists from the first moment: keys answer it, the 9P log
+ says `ask` at once, a script's `answer` works; only the band waits.
+
+## Why 400 ms
+
+Typed in one go, the `j` after `SPC d` lands 100-250 ms after the `d`
+(a leader sequence's inter-key gap). Above ~300 ms it is a pause, the hand
+waiting to see something happen. 400 ms clears a relaxed typist with margin
+and is still quick enough to read as "it is asking", not "it is broken".
+Key-hint popups elsewhere (which-key) wait a few hundred ms for the same reason. It is a compile-time
+constant beside `del_question` (keys are compiled in); a Runtime setting
+would be one line in config if the author wants to tune it live.
+
+## Tests
+
+- `window mode d deletes the outlined pane and asks k or j, c collapses
+ it, and the mode stays` (pardes.zig): c twice restores the height; d asks,
+ Esc keeps it, d j gives the rows below and the outline follows; d with one
+ neighbour closes at once onto it; labels hold none of h j k l d c.
+- `the Del question shows only once its delay is up: a quick SPC d j never
+ sees it`: no prompt band before the due time, nextWake at it and not
+ past one frame, the band after, no wake once stepped past; a fast
+ `SPC d j` closes with the band never showing it.
+- The old Del test moves the clock to the due time before looking at the
+ band. `test/snapshots/delask.snap` waits out the delay (`settle 700`)
+ before `snap asked`; its golden is unchanged (it raced otherwise: the
+ first `stable 400` saw no change and captured the band empty).
+
+## Open questions, positions
+
+- Should `d` leave window mode after closing? Position: no. The point of a
+ mode is a run of layout edits (`Ctrl-w d j d c`), and the outline landing
+ on the pane that grew says where you are; Enter/Esc end it as ever.
+- `d`/`c` taken from the labels: the 21st and 22nd panes lose a letter.
+ Position: fine; past 20 panes you move anyway. The alternative (labels
+ only after a prefix) costs a key on every jump.
+- Del's question from a click or 9P never asks, so the delay touches only
+ the keyboard paths that ask today.
+- Pushback: the hint could be the message row's own lingering text instead
+ of the prompt band, but the band is where the answer's keys are named and
+ the caret logic already knows it; kept.
diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json
index 88c9d864..db1031a0 100644
--- a/docs/typ/builtins-gui.json
+++ b/docs/typ/builtins-gui.json
@@ -154,7 +154,7 @@
{"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."},
{"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."},
{"name": "Vignette", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off, 0-3", "doc": "The window's corners fall into shade: a level, 0 (off) through 3."},
- {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one."},
+ {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."},
{"name": "WindowOpacity", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "The window's opacity, a percentage."},
{"name": "Wrap", "leader": "SPC t w", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "Long lines wrap onto the next row, on or off."},
{"name": "WsDiagnostics", "leader": "SPC l D", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the workspace's diagnostics from the language server."},
diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json
index 01ae6bc5..6bdca598 100644
--- a/docs/typ/builtins-tty.json
+++ b/docs/typ/builtins-tty.json
@@ -136,7 +136,7 @@
{"name": "Unmount", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Unmount the 9P tree mounted under /n/<name>."},
{"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."},
{"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."},
- {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one."},
+ {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."},
{"name": "Wrap", "leader": "SPC t w", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "Long lines wrap onto the next row, on or off."},
{"name": "WsDiagnostics", "leader": "SPC l D", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the workspace's diagnostics from the language server."},
{"name": "WsSymbols", "leader": "SPC l S", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Search the workspace's symbols for its argument."},
diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ
index 76f4b866..d8939c4c 100644
--- a/docs/typ/cheatsheet.typ
+++ b/docs/typ/cheatsheet.typ
@@ -29,7 +29,7 @@ One button: Alt/Option-click is #btn("B2"), Cmd/Super-click #btn("B3"), sweeps t
#tag("Save Tty Collapse Del", path: "/home/me/notes.txt")
#tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src")
#tag("Tty PdfSections PdfTint Collapse Del", path: "manual.pdf [1/12]")
-- #word("Del") over unsaved text refuses once; again discards. #word("Del") `j`: rows below.
+- #word("Del") over unsaved text refuses once; again discards. #word("Del") `j`: rows below. #key("SPC d") between two panes takes #key("k") (rows above) or #key("j") (below), asking only if you pause.
- #word("Undo") #word("Redo") #word("Edit") #word("Mode") work typed anywhere. #doc("tags")
== #word("Look") addresses
@@ -71,7 +71,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla
== Keys: panes
#pairs(
- [#key("Ctrl-w")], [window mode: #keys("h", "j", "k", "l") move the outline, #key("Enter")/#key("Esc") or a pane's letter focuses (not in insert or raw `$`)],
+ [#key("Ctrl-w")], [window mode: #keys("h", "j", "k", "l") move the outline, #key("d") deletes it (then #key("k")/#key("j") between two), #key("c") collapses it, #key("Enter")/#key("Esc") or a pane's letter focuses (not in insert or raw `$`)],
[#key("Esc")], [back to the previous pane (insert: to normal)],
[#key("Shift-Esc")], [back to the previous pane from any mode but raw, where it is the program's Esc; needs the kitty keyboard protocol or the GUI, elsewhere a plain Esc],
[#keys("Ctrl-o", "Ctrl-i")], [jump history back, forward; this file first. #key("Ctrl-i") is #key("Tab") without the kitty protocol: #key("SPC j i")],
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 65c7334d..9fd33e60 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -54,7 +54,7 @@ it is a plain Esc. The previous pane is the last one you jumped from, else
the next pane down the column.
#pairs(
- [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag],
+ [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag. #key("d") is #word("Del") on the outlined pane (between two panes it waits for #key("k") or #key("j"), as #key("SPC d") does) and the outline moves to the pane that took its rows; #key("c") is #word("Collapse"). The mode stays on for the next key],
[#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way (#word("JumpScope") `all`: every place in order). #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons],
)
@@ -214,7 +214,10 @@ and a terminal's #key("/") still ask on the message row and list a
in `+Unsaved`; #word("Del") again discards it.
#word("Exit") (or #key("SPC q")), #word("Restore") and #word("Delcol")
refuse once the same way. #key("SPC d") between two panes also asks which
-takes the rows: #key("k") above, #key("j") below.
+takes the rows: #key("k") above, #key("j") below. Typed straight on,
+#key("SPC d") then #key("j") just closes the pane; the question shows on its notice band
+only if no answer has come after a moment, a hint for a Del that seemed to
+do nothing.
= Terminals <terminals>
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 386b9f0f..3ddcd881 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -593,7 +593,8 @@ no newline, as acme's has none (`cat ctl; echo`). It
takes:
- the pane builtins: #word("Del") (from the keyboard between two panes it
- asks which takes the rows; a click, a ctl write or an `init` line never
+ asks which takes the rows, the question on the notice band after 400 ms
+ and in the log at once as `ask`; a click, a ctl write or an `init` line never
asks and gives them to the pane above; #word("Del") `k`/#word("Del") `j`, or
#word("DelAbove")/#word("DelBelow"), give its rows to the pane above or
below), #word("Save") `[path]` (bare, on a `+`-named pane that is no output,
@@ -605,7 +606,8 @@ takes:
keyboard to the pane beside it that way, up from a column's top pane to
its tag; #word("Window") (#key("Ctrl-w"), #key("SPC w")) picks the pane
first: #keys("h", "j", "k", "l") move an outline, #key("Enter") or
- #key("Esc") or a pane's letter focuses.
+ #key("Esc") or a pane's letter focuses, #key("d") is #word("Del") and
+ #key("c") #word("Collapse") on the outlined pane.
- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`). It is an undo step, so #word("Undo") brings back what was there: the sure way back to the file on disk.
- `lock`/`unlock` (acme's). The lock binds only clients that take it and
belongs to the open that wrote it: `exec 3>$pane/ctl; echo lock >&3; ...; exec 3>&-`. A `lock` another open holds fails at once, `file in use`