path: root/docs/typ/guide.typ

// The guide: pardes day to day, the path a newcomer reads once. Edge cases
// live in the reference, the pager and the language servers in setup, the
// keys on the cheatsheet.
#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated

pardes reads the text on its screen as things to do, with two builtins.
#word("Look") (right-click) on `src/bar.c:12` opens that line; on a URL,
the browser; on any other word, its next place. #word("Exec")
(middle-click) on `Save` runs that builtin; on `make`, a shell line. The
screen is columns of panes, each a tag (a line of words) over a file, a
terminal, a PDF or an image. The keys are helix's, and every session is a
virtual filesystem, served over 9P, for scripts.

#annotated("/docs/site/media/themes/orchard.png", (640, 513),
  ([the workspace tag: words for the whole session], 330, 11),
  ([a column's tag], 400, 34),
  ([a pane's tag: its path, then its words], 560, 58),
  ([the box: the pane's mode, and the handle to drag it], 8, 58),
  ([the body: here a file, below it a terminal], 500, 128),
  ([the scrollbar: how much of the body is in view], 8, 160),
)

#glossary("Words you'll see", <words>,
  [tag], [the line of words over a pane, a column or the screen; every word in it can be clicked],
  [the pane with the keyboard], [where your keys go; one pane at a time],
  [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],
  [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")],
  [the box], [left of a pane's tag: drag it to move or resize the pane; it shows the mode, and marks unsaved text (`*`, or filled in the window)],
)

= Modes <modes>

Each pane keeps its own mode, shown in the box left of its tag.

#pairs(
  [normal (blank)], [keys move and select; an edit acts on the selection. File and PDF panes start here, and so does a terminal from #key("Alt-n").],
  [insert (`^`)], [keys type. #keys("i", "a", "o") and the rest enter it.],
  [raw (`$`), terminals only], [keys go to the program. A terminal from #word("Tty"), the shell a bare `pardes` starts with, and a command pane start here.],
)

#key("Ctrl-b") switches a terminal between raw and normal; in normal its
text is a page to move over and copy from, prompts hidden. #word("Mode")
in the tag steps raw, normal, insert.

#pairs(
  [normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #key("Shift-Esc"): the same.],
  [insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.],
  [raw `$`], [#key("Esc"): to the program, except at a shell prompt with nothing typed on it, where it goes back to the previous pane. #key("Shift-Esc"): always back. Either way the terminal stays `$`.],
  [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.],
)

#key("Shift-Esc") needs the kitty keyboard protocol or the GUI; elsewhere
it is a plain Esc. The previous pane is the last other pane on the jump
list, else the next pane down its column.

#pairs(
  [#key("Ctrl-w") #key("h")], [the keyboard to the pane on the left; #key("j") below, #key("k") above, #key("l") right],
  [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list)],
)

Raw mode sends every key but #key("Ctrl-b"), Esc and the paste chords to
the program: leave it before #key("Ctrl-w") or #key("Alt-n").

= The mouse <mouse>

#pairs(
  btn("B1"), [select; a click puts the cursor there and gives the pane the keyboard. In a tag it starts typing, in insert mode. A double click selects the word; at a line's start or end, the line; just inside a bracket or quote, up to its match.],
  btn("B2"), [#word("Exec"): a builtin word runs, anything else is a shell line.],
  btn("B3"), [#word("Look"): open the file, address, directory or URL, else find the word's next place.],
  chord("B1", "B2"), [cut the selection],
  chord("B1", "B3"), [paste over it],
  chord("B1", "B2", "B3"), [copy],
)

With one button, as on a trackpad, Alt-click (Option on a Mac) is #btn("B2") and Super-click (Cmd) is #btn("B3"), sweeps included; Ctrl-click stays the language server's definition, a program that takes the mouse gets the plain click, and in a terminal only Alt-click works, since Super never reaches pardes there.

#btn("B3") on `src/bar.c:12:5:` in a compiler's error opens `src/bar.c` at
line 12, column 5: a click with no drag takes the run of letters, digits
and `. - + / : @ _ ~` under it, a trailing `:` dropped. Drag to say
exactly what you mean. #key("Enter") and #key("Tab") in normal mode are
#word("Look") and #word("Exec").

#key("y") yanks and #key("p") pastes after (#key("x") #key("y") then
#key("p") puts the line in below), through registers every pane shares;
#key("SPC y") and #key("SPC p") use the system clipboard.

= Tags <tags>

#tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit")
#tag("New Tty Find Grep Joincol Delcol")
#tag("Save Tty Collapse Del", path: "/home/me/notes.txt")

A tag is text with undo: type `make` into one and #word("Exec") it, or
delete the words you never use. #key(":") moves the keyboard onto the
tag's #word("Save") the first time (#key("Tab") runs it), and back. Any word runs from any
tag: #word("Exit") in a pane's tag quits too. Edit the path to
`/home/me/notes2.txt` and press #key("Enter"): the next #word("Save")
writes there.
#word("Collapse") folds a pane to its tag. Drag the grip up or down to
resize, or onto another column to move the pane.

= Where commands run and panes go <command-panes>

#btn("B2") on a line that is no builtin (`make`, `git log`) runs it with
the #word("Shell") setting's `-c`, by where you clicked:

#pairs(
  [a terminal's text or tag, at a prompt with nothing typed], [typed into that shell, in its current directory],
  [any other pane's text or tag], [a command pane in that pane's directory, in the last column],
  [a column's tag], [a command pane in the session's directory, in that column],
  [the workspace tag], [a command pane in the session's directory, in the last column],
)

So run `make` from a column or the workspace tag, not a file's. The
keyboard stays where it was, and the command pane's tag ends in `running`,
then `exit N`:

#tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0")

The next command for that directory reuses a finished command pane.
#word("Kill") `make` stops what pardes started whose line starts with
`make`; #word("Exit") quits pardes. #word("Save") or #word("Del") in a
column tag acts on that column's pane with the keyboard, or its first.

Every other new pane goes into the *active column*: the column you last
typed or left-clicked in, or the one that got the last new pane. It
takes the keyboard, except a listing, which opens below the pane that
asked and leaves it the keyboard, so #keys("n", "N") walk the listing.
#btn("B3") on a file open in another column jumps there, but the next new
pane still lands in the old column until you type or click.
#word("Placement") `pardes` picks other rules (#doc("reference", section: "placement")).

Closing a column's last pane leaves it empty; #word("Delcol") and
#word("Joincol") take columns away. Closing the session's last pane quits
pardes.

= Look <looking>

#pairs(
  addr("notes.txt"), [opens it, or goes to the pane already showing it],
  addr("notes.txt:12"), [line 12],
  addr("notes.txt:/TODO/"), [the next match of `TODO`],
  addr("src/"), [`ls` typed into a terminal idle there, else a new terminal there],
  addr("https://ziglang.org"), [the browser],
)

#key("Enter") does the same from the keyboard; the other address forms are
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.

#pairs(
  [#key("/") `TODO` #key("Enter")], [a `+Search` of the lines holding `TODO`, the cursor on the first; #keys("n", "N") step through],
  [#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],
)

= Unsaved panes <unsaved-panes>

#word("Del") on a pane with unsaved text (marked on its grip) refuses
once, saying `1 unsaved pane — Del again to discard`, and lists the pane
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.

= Terminals <terminals>

#tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src")

- #word("Tty") opens a terminal in the pane's directory, #key("Alt-n") one in
  the session's directory; #word("Tty+bash") picks the shell.
- #word("Del") closes a terminal and its shell at once, running or not, and
  a shell that exits closes its pane.
- #word("Save") writes the scrollback to a path it asks for.
- #word("Filter") maps the program's colours through the theme.
- #word("Petscii") draws a program's images as glyph art instead of pixels.
- In raw mode Ctrl-V types what you yanked, Ctrl-Shift-V the clipboard.
- A program that tracks the mouse gets #btn("B1") and the wheel;
  #btn("B2") and #btn("B3") stay pardes's. Hold Shift to swap.
- #word("Repl") `python` in its tag makes #btn("B2") on a `.py` pane send the text
  to that REPL.
- `git log` and `man` open in a `+Pager` pane (#doc("setup", section: "pager")).

= Reviewing diffs <reviewing-diffs>

`git diff` run as a command, or a `.diff` or `.patch` opened, is drawn as
a diff, each hunk in its file's language. #btn("B3") on:

#pairs(
  [`diff --git`, `---`, `+++`], [the file],
  [`@@ -3,7 +3,8 @@`], [the hunk's first new line],
  [a line's `+`, `-` or space], [that line in the new file],
)

= `pardes FILE` and `--wait` <editor>

In a pane's shell:

```
pardes notes.txt          open it here and return at once (acme's B)
pardes --wait notes.txt   return when that pane closes (acme's E)
```

A file not there yet opens empty, and #word("Save") creates it.
`--wait` makes pardes an `EDITOR` (#doc("setup", section: "editor-setup"));
refusals and `--nested` are in the reference.

= Keys <keys>

#pairs(
  [#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; step through everything #word("Look") would open, across panes],
  [#key("g l")], [line end],
  [#key("SPC ?")], [every leader path; #word("Help") every key and builtin; #word("Tutor") (#key("SPC h t")) practises them],
  [#keys("g d", "g r"), `SPC l`], [the language keys, once a server is installed (#doc("setup", section: "language-servers"))],
)

The keys are helix's, and helix's
#link("https://docs.helix-editor.com/keymap.html")[keymap] is their full
reference. Where pardes differs (#key("Esc") leaving the pane, the
#key("SPC") paths, #key("Ctrl-w"), #key("Ctrl-b")), this guide and the
cheatsheet (#doc("cheatsheet")) say so.

= Sessions <sessions>

```
pardes --detach=work &      a session with no screen of its own
pardes --attach=work        show it here
```

The session owns the panes, shells and files; frontends come and go, and
all of them see the same screen. #word("Attach") `work` (#key("SPC s a"))
switches this window to it; #word("Detach") (#key("SPC s D")) leaves it
running.

= Config <config>

#word("Config") (#key("SPC f c")) opens the startup file,
`~/.config/pardes/init`: one builtin a line, run at start, `#` a comment.

```
Theme atelier
Shell zsh
# Placement acme is the default; Placement pardes picks the other rules
```

#word("DumpConfig") opens every live setting as the line that sets it.
#word("Dump") saves the workspace and #word("Restore") brings it back
(what a dump keeps is in the reference). Keys are compile-time, in
`src/config.zig`.