diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-24 12:43:02 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-24 13:11:11 -0300 |
| commit | 1af098381515fbe3a4fe678cd023c7fd74418ae1 (patch) | |
| tree | 34f8f1495ddbea9542d23af68db53f244a1ec4c5 /docs | |
| parent | 8ac6db5662dd2db0f082e1651835f1db36e235f8 (diff) | |
| download | pardes-1af098381515fbe3a4fe678cd023c7fd74418ae1.tar.gz pardes-1af098381515fbe3a4fe678cd023c7fd74418ae1.zip | |
Search converge 5/6: the old search pipeline phased out, the notice-band / for texts, Find/Grep prompts and walks on the loop, +Recent, n/N as Look-the-next-row; docs, tutor, Help and goldens to the query pane
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/helix-keys.md | 8 | ||||
| -rw-r--r-- | docs/typ/builtins-gui.json | 2 | ||||
| -rw-r--r-- | docs/typ/builtins-tty.json | 2 | ||||
| -rw-r--r-- | docs/typ/cheatsheet.typ | 6 | ||||
| -rw-r--r-- | docs/typ/guide.typ | 46 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 28 |
6 files changed, 68 insertions, 24 deletions
diff --git a/docs/helix-keys.md b/docs/helix-keys.md index 8155685f..fa06c9a6 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -134,14 +134,14 @@ language-backend queries, and the shell pipe. | `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 | | `SPC y` `SPC Y` `SPC p` `SPC P` `SPC R` | helix's clipboard menu on helix's own letters: yank the selection to the system clipboard (`ClipYank`) or the PRIMARY selection alone (`ClipYankMain`), paste the system clipboard after (`ClipPaste`) / before (`ClipPasteBefore`) the selection, replace the selection with it (`ClipReplace`) | the same as `"+y`, `"+p`, `"+P`, `"+R`: register `+` (and `*`) IS the desktop's clipboard, the only register that reaches it. `SPC y` writes `+` alone, as helix's does, not the default register too. Builtins rather than bare chords because a leader path names a builtin: they land in Help's index and are executable words like every other verb. The clipboard holds one text, so N values go out joined by newlines, as helix sends them. On a tty the write is OSC 52 out and the READ is OSC 52 back, which many terminals refuse or gate — so `SPC y` works there and `SPC p` can be a no-op | out of corpus | | a paste from the OUTER terminal | one `Event.paste`, spliced in at the cursor | the tty shell enables bracketed paste and coalesces `paste_start`..`paste_end` into a single event; before that the bytes arrived as individual key presses and normal mode RAN them, which is how a pasted `d` deleted a line. The bytes deliberately never enter the yank register — clipboard and default register are separate stores in both directions | pardes-specific | -| `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the pattern is typed on a line of its own on the pane's notice band, Enter fills the buffer, and its rows are ordinary look targets. Enter also goes to the first row using `Pardes.lookFirstHit`, so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | kept as-is; not in the corpus (helix `/` is regex search). Find and Grep answer with other files and deliberately do not jump. `LookNext` / `LookPrev` select subsequent result rows | pardes-specific | -| `n` / `N` | next / previous regex match in the current text, using the last search register; counts repeat and ends wrap | only the primary selection is replaced; in select mode each match is added and becomes primary. Named registers work. `*` sets the pattern from selections with word boundaries, `Alt-*` without. The former Look ring is `LookNext` / `LookPrev`, `SPC j n` / `SPC j p`. The change is bookmarked `pardes-nN-helix`; its predecessor is `pardes-nN-before-helix`. PDFs retain their location-result navigation | helix-verified | +| `/` (a text) | a query pane under the pane (`src/Query.zig`): a `+Search` whose line 1 is the query, typed into; helix's regex with smart case, every match tinted and ticked on the rail as you type (the pane's places, `src/Places.zig`), the first after the cursor selected (helix's incremental preview). `Ctrl-n`/`Ctrl-p` step while typing; Enter lands, fills `/` and keeps the rows as text; Esc while typing restores the text and closes the pane. Line 1's first word names the source (`/`, `Find`, `Grep`, `Recent`, `Panes`, `Symbols`, `All`, `Refs`, `Def`, `Impl`, `Diagnostics`), helix's pickers as one pane. A terminal's and a PDF's `/` keep the notice-band prompt and its `+Search` | helix's `/` semantics (regex, smart case, preview); the pane is pardes' | pardes-specific | +| `n` / `N` | next / previous match of the text's places when a query pane fed them (a `/`, a list's places in this text: refs, diagnostics, a Grep's hits), round the ends without a message; else the last search register's regex in the current text, as before; counts repeat | only the primary selection is replaced; in select mode each match is added and becomes primary. Named registers work. `*` sets the pattern from selections with word boundaries (`Alt-*` without) and seeds the text's query pane with it, the keyboard staying. The former Look ring is `LookNext` / `LookPrev`, `SPC j n` / `SPC j p`. PDFs retain their location-result navigation | helix-verified | | insert: printable text | file: real edit; terminal: typed run splice | | helix-verified (file) | | insert: `Enter` | newline; keeps the current full indent levels and adds one 4-space logical tab when the text before the cursor ends in `(`, `[`, `{`, or `)` (including `})`) | plain lines match `insert_newline`; delimiter heuristic is pardes-specific | helix-verified (plain) / pardes-specific (delimiter) | | insert: `Backspace` (+ `Shift-Backspace`) | delete prev char, joins lines at col 0; in a line's leading blanks, back to the previous 4-column indent stop (a whole unit when on one; a tab still goes alone) | matches `delete_char_backward` and its dedent; `Ctrl-h` alias in B | helix-verified | | insert: `Up` `Down` `Left` `Right` | move cursor | matches helix's "not recommended" insert arrows | helix-verified | -| `gd` `gD` `gy` `gi` `gr` | LSP definition / declaration / type-definition / implementation / references. One answer jumps straight there; several fill `+Search`, where `LookNext` / `LookPrev` walk and Enter opens | Ctrl+left-click is the mouse spelling of `gd`; language support depends on the configured backend | out of corpus | +| `gd` `gD` `gy` `gi` `gr` | LSP definition / declaration / type-definition / implementation / references. One answer jumps straight there; several (definition, implementation, references) fill the text's query pane, line 1 `Def`/`Impl`/`Refs`, their places in the text tinted and stepped by `n`/`N`; the others fill `+Search`, where `LookNext` / `LookPrev` walk and Enter opens | Ctrl+left-click is the mouse spelling of `gd`; language support depends on the configured backend | out of corpus | | `]d` `[d` / `]D` `[D` | step the diagnostics list / go to its last or first; if no list is up, asking the backend for one is part of the press | | out of corpus | | `=` | `format_selections` — writes a `- old` / `+ new` diff into `+Lsp` | deliberate divergence: the seam returns ROWS, not edits, so this SHOWS the formatting instead of applying it. Not in the corpus, so there is no waiver to name — the query leaves the core as an effect the headless harness has no shell to perform | out of corpus | | `Ctrl-o` / `Ctrl-i` | jumplist back / forward (also Mouse4 / Mouse5 in SDL, macOS and web); successful navigation clears selections in both panes and places the cursor at the saved location; raw tty forwards both to the child — the `Back` / `Forward` builtins, also on `SPC j o` / `SPC j i`, with `SPC j l` rendering the stack as a buffer; a closed file's entry stays, marked `(closed)`, and a jump to it opens the file again at its place | helix binds both keys (`jump_backward` / `jump_forward`) but to a POSITION jumplist; pardes' stack is over panes and focus, so the keys agree and the semantics do not. `Ctrl-i` and Tab are the same byte under the legacy encoding; there Tab keeps meaning execute, and the pair only separates where the host speaks the kitty keyboard protocol | pardes-specific | @@ -353,7 +353,7 @@ text. | Key(s) | Helix behavior | Reason | | --- | --- | --- | -| `?` | reverse search prompt | pardes keeps its own `/` plain substring search into an output buffer. `*`, `Alt-*` and search-repeat `n`/`N` are implemented and verified above | +| `?` | reverse search prompt | pardes' `/` is a query pane (above); `N` steps backward. `*`, `Alt-*` and search-repeat `n`/`N` are implemented and verified above | | `Space` mode: `f F e . b j g G ' w c C Alt-c / ?` | pickers, global search, palette | pickers and the command palette do not exist here — but the KEY is taken: pardes' own leader runs the acme builtins (section A). Two halves of helix's space mode DO exist and are in section A: the clipboard menu (`<space>y Y p P R`, helix's letters on helix's leader) and the LSP menu, moved one prefix deeper to `SPC l k/r/a/h/s/S/d/D` because `d`, `k`, `s` and `h` were already pardes' most-pressed keys | | 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 | diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json index c238955c..88c9d864 100644 --- a/docs/typ/builtins-gui.json +++ b/docs/typ/builtins-gui.json @@ -51,7 +51,7 @@ {"name": "Forward", "leader": "SPC j i", "also": ["C-i"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-i: one step forward again, up to wherever Back started."}, {"name": "Get", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "acme's Get: the pane's file read again, its unsaved edits refused once as Del refuses them."}, {"name": "Grain", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off, 0-3", "doc": "The page takes a fine, still grain, like paper: a level, 0 (off) through 3."}, - {"name": "Grep", "leader": "SPC f g", "also": ["topbar"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Find's sibling: Find matches file NAMES under this pane's directory, Grep matches file CONTENTS under every pane's directory at once."}, + {"name": "Grep", "leader": "SPC f g", "also": ["topbar"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Find's sibling: Find matches file NAMES under this pane's directory, Grep matches the LINES of those files, on the disk engine's worker."}, {"name": "GripWidth", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "The grip and scrollbar width, as a percent of the theme's rail."}, {"name": "Help", "leader": "SPC ?", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the help: every key and every builtin."}, {"name": "Hover", "leader": "SPC l k", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Ask the language server about the symbol under the cursor."}, diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json index 791eef63..01ae6bc5 100644 --- a/docs/typ/builtins-tty.json +++ b/docs/typ/builtins-tty.json @@ -45,7 +45,7 @@ {"name": "FocusTint", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "The focused pane's and column's tags are tinted, on or off."}, {"name": "Forward", "leader": "SPC j i", "also": ["C-i"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Ctrl-i: one step forward again, up to wherever Back started."}, {"name": "Get", "leader": null, "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "acme's Get: the pane's file read again, its unsaved edits refused once as Del refuses them."}, - {"name": "Grep", "leader": "SPC f g", "also": ["topbar"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Find's sibling: Find matches file NAMES under this pane's directory, Grep matches file CONTENTS under every pane's directory at once."}, + {"name": "Grep", "leader": "SPC f g", "also": ["topbar"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Find's sibling: Find matches file NAMES under this pane's directory, Grep matches the LINES of those files, on the disk engine's worker."}, {"name": "Help", "leader": "SPC ?", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the help: every key and every builtin."}, {"name": "Hover", "leader": "SPC l k", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Ask the language server about the symbol under the cursor."}, {"name": "InactiveDim", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "Fade the unfocused panes' text by a percentage, 0 through 100, 0 off."}, diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ index 7b140a04..76f4b866 100644 --- a/docs/typ/cheatsheet.typ +++ b/docs/typ/cheatsheet.typ @@ -59,7 +59,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla [#keys("i", "a", "I", "A", "o", "O")], [insert; #key("Esc") back to normal], [#keys("s", "S")], [regex: a cursor per match, split], [#keys("C", ",")], [cursor on next line; keep primary], - [#keys("/", "n", "N")], [search, next, previous], + [#keys("/", "n", "N")], [search (a query pane), next, previous], [#keys("m i", "m m")], [textobject, matching bracket], [#key("|")], [pipe each selection through the shell], [#keys("g d", "g r")], [definition, references (language server)], @@ -87,6 +87,8 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla key("SPC f f"), word("Find"), key("SPC f g"), word("Grep"), key("SPC f r"), word("Recent"), + key("SPC b b"), word("Panes"), + key("SPC s s"), [declarations], key("SPC f c"), word("Config"), key("SPC d"), word("Del"), key("SPC n t"), word("Tty"), @@ -119,7 +121,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla `git diff` output is a diff: #btn("B3") on a file line, an `@@` or a line's `+`/`-` jumps there. #doc("tags", section: "reviewing-diffs") == Finding things -- #word("Find") `name`, #word("Grep") `text` (literal): a `+Search` listing. #word("Recent"): files lately. #word("Help"), #word("Tutor"). +- A query pane under the pane: line 1 the query, its first word the source: `/pat`, `Find name` (fuzzy), `Grep text` (literal), `Recent`, `Panes`, `Symbols`, `All`. #keys("Ctrl-n", "Ctrl-p") step, #key("Enter") lands and keeps the rows, #key("Esc") puts things back. #word("Help"), #word("Tutor"). == Sessions `pardes --detach=work`; `--attach=work` or #word("Attach") `work`; #word("Detach") leaves it running. #doc("detached") diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index e60b4231..65c7334d 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -20,9 +20,9 @@ [the session's directory], [where pardes started, or the directory `pardes DIR` named; workspace and column tags run there], [active column], [where the next new pane goes (below)], [command pane], [a terminal that runs one command line and shows its output], - [`+` names], [panes pardes makes, named in their directory: `+New` a scratch (text with no file yet), `+Search` a listing of places, `+Pager` paged text, `+Errors` output, `+Unsaved` the panes holding unsaved text], + [`+` names], [panes pardes makes, named in their directory: `+New` a scratch (text with no file yet), `+Search` a query pane or a listing of places, `+Pager` paged text, `+Errors` output, `+Unsaved` the panes holding unsaved text], [serial], [a pane's number, never reused: the `3` in `@p3:12` and in 9P paths], - [message row], [the line where pardes says what happened, and asks: answer a prompt (a search, #word("Save")'s path) with #key("Enter"), cancel it with #key("Esc")], + [message row], [the line where pardes says what happened, and asks: answer a prompt (#key("s")'s regex, #word("Save")'s path) with #key("Enter"), cancel it with #key("Esc")], ) = Modes <modes> @@ -166,11 +166,45 @@ on the cheatsheet. A relative path is found in the directory of the pane the #word("Look") came from, then of each pane on the jump list, most recent first. += Search <search> + +#key("/") opens a query pane under the pane: a `+Search` whose first line +is the query, typed into, and whose rows are what it finds, made again at +each key. It takes its rows from the pane it searches and from no other, +is born #word("SearchRows") rows tall and never resizes itself; nothing +found is a count of `0` in its tag, not an exit. + #pairs( - [#key("/") `TODO` #key("Enter")], [a `+Search` of the lines holding `TODO`, the cursor on the first; #keys("n", "N") select the next or previous match], - [#word("Find") `conf`], [a `+Search` of the files below the pane's directory with `conf` in their names], - [#word("Grep") `TODO`], [a `+Search` of the lines holding `TODO`, literally, under every pane's directory], + [#key("/") `vw`], [every match in the text tinted and ticked on its scroll rail, the first after the cursor selected; the rows under line 1 are the lines holding it, a line number in the gutter, each under the declaration it is in], + [#keys("Ctrl-n", "Ctrl-p")], [the next or previous match, typing; the text follows it], + [#key("Enter")], [the keyboard on the match, the pattern in `/`, the rows kept as text (#word("Save") keeps them as a file)], + [#keys("n", "N")], [the next or previous match in the text, round the end without a word], + [#key("Esc")], [typing: the text as it was, the query pane closed], + [#key("*")], [the selection as line 1, the keyboard staying in the text], ) + +Line 1's first word names what it searches, and editing the word changes it: + +#pairs( + [`/pat`], [the pane's own text: a regex, any case unless it has a capital (#key("/"))], + [`Find name`], [the files below the pane's directory, by a fuzzy match of their names (#key("SPC f f"), #word("Find"))], + [`Grep text`], [the lines of those files holding `text`, literally (#key("SPC f g"), #word("Grep")); past 2000 lines #word("More") goes on], + [`Recent name`], [the files opened lately (#key("SPC f r"), #word("Recent"))], + [`Panes name`], [the open panes (#key("SPC b b"), #word("Panes"))], + [`Symbols name`], [the text's declarations (#key("SPC s s"))], + [`All pat`], [every open pane's text, its rows under each pane (#key("SPC /"))], + [`Refs`, `Def`, `Impl`, `Diagnostics`], [the language server's lists; their places in the text tinted as a `/`'s are, `]d` stepping the diagnostics], +) + +A row in a file no pane shows is shown in a `+Preview` under the query +pane, following #keys("Ctrl-n", "Ctrl-p") and #btn("B1"), never the +pointer; #key("Enter") makes the preview that file's pane where it stands. +#btn("B3") on a row's line number looks at the row; #btn("B2") on line 1 +runs it again. The next search from the same pane reuses its query pane, +its kept rows back on #key("Esc") (#word("SearchPane") `new`: a pane each; +#word("SearchPlace") `column`: in a finder column at the right). A PDF's +and a terminal's #key("/") still ask on the message row and list a +`+Search`. #clip("search") = Unsaved panes <unsaved-panes> @@ -281,7 +315,7 @@ refusals and `--nested` are in the reference. [#key("w") #key("d")], [select a word, delete it: motions select, edits act on the selection], [#key("x"), #key("v"), #key(";")], [select the line; extend; collapse to the cursor], [#key("s")], [a cursor per regex match; every edit acts at each], - [#key("/"), #keys("n", "N")], [substring search; repeat the search in the current text, wrapping at the ends], + [#key("/"), #keys("n", "N")], [search the text in a query pane (#link(<search>)[Search]); step its matches, round the ends], [#keys("SPC j n", "SPC j p")], [#word("LookNext") / #word("LookPrev"): select locations across panes; #key("Enter") opens one], [#key("g l")], [line end], [`12G`], [line 12; a bare #key("G") does nothing], diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index c14ad659..386b9f0f 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -909,7 +909,8 @@ at 200, ending in `…`. Control characters become spaces. pane from the root). - #file("/recent"): up to 200 files, PDFs and images, most recent first, `open <path>` or `closed <path>`; kept in `$XDG_STATE_HOME/pardes/recent`. - #word("Recent") shows them in a pane, an open one at its dot now and a + #word("Recent") lists them in a query pane (line 1 `Recent`, the rest + narrowing them by a fuzzy match), an open one at its dot now and a closed one at its last (a PDF's is its page); a #word("Look") of a row reopens it there. - #file("/status"): `pid`, `version`, `panes`. @@ -972,15 +973,22 @@ one a #file("exec") open still holds is never reused. In a command pane, #key("n = Find and Grep <find-grep> -#word("Find") matches file names, #word("Grep") the text of lines, both literally and -ignoring ASCII case. #word("Grep") reads whole files and stops at 512 -hits, #word("Find") at 512 names. The walk stops at 20000 files or 100000 entries, -16 deep, and passes over `.git`, `.jj`, `target`, `node_modules`, -`.venv`, `__pycache__`, `.zig-cache` and `zig-out`. A cap hit, or a -directory it could not open, is said at the end: `cut at 512 hits`, `walk cut at N entries`, `N -directories skipped: permission denied`. A search that finds nothing and -skipped nothing fails, `Grep: text not found`, and leaves the `+Search` as -it was. +Both fill the asking pane's query pane (#doc("guide", section: "search")), +line 1 `Find name` or `Grep text`, and run on a worker thread, never on +the loop that draws: `rg` when it is on `PATH` (`rg --files` and `rg --json +--fixed-strings --smart-case`, so `.gitignore` is honoured and hidden files +are passed over), else pardes's own walk, sorted, 16 deep, passing over +dot-directories, `.git`, `.jj`, `target`, `node_modules`, `.venv`, +`__pycache__`, `.zig-cache` and `zig-out`. #word("Find") lists the files once +and matches their names fuzzily at each key (the best first, 200 shown); +#word("Grep") matches the text of lines literally, any case unless the text +has a capital, once the typing pauses (80 ms), and stops at 2000 lines: +#word("More") (in the query pane's tag) goes on for 2000 more. A directory the +walk could not open is said under the rows: `N directories skipped: +permission denied`. A new query cancels the last; rows of a query no +longer asked never land. Written to #file("exec") (a script) the search runs +to its end before the write is answered, and one that finds nothing fails, +`Grep: text not found`, `Find: name not found`, its query pane's count `0`. = On screen <on-screen> |
