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

pardes reads the text on its screen as things to do. Right-click (#btn("B3"))
any text to *look* at it: open the `file:line`, address or URL it names, or
else find the text. Middle-click (#btn("B2")) it to *execute* it: run the
builtin it names, or else run it as a shell line. Everything else is where
that happens: columns of panes, each a tag (a line of words) over a body
that is a file you edit, a terminal, a PDF or an image, with a tag for each
column and the workspace above. The keys are helix's, in modes, and every
session is also a virtual filesystem, served over 9P, for scripts.

#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, 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 has its own mode and keeps it while you are elsewhere. The box
at the left of a pane's tag shows it.

#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 mode
its prompts are hidden and its text is a page to move over and copy from.
#word("Mode") in the tag steps raw, normal, insert.

#pairs(
  [normal], [#key("Esc"): back to the previous pane (#word("Last")). #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.],
)

Unlike helix, #key("Esc") in normal mode leaves the pane: it is how you go
back. #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. #key("Ctrl-w") then
#keys("h", "j", "k", "l") moves the keyboard to the pane left, below,
above or right; #keys("Ctrl-o", "Ctrl-i") walk back and forward through the
places you have jumped to, the jump list. In raw mode every key but #key("Ctrl-b"), Esc and the
paste chords goes to the program, so #key("Ctrl-w") and #key("Alt-n") need
you out of raw mode first.

= 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"), [execute: a builtin word runs, anything else is a shell line.],
  btn("B3"), [look: open the file, address, directory or URL, else find the word's next place.],
)

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

Hold #btn("B1") and click #btn("B2") to cut the selection, #btn("B3") to
paste over it, both one after the other to copy. #key("y") yanks and
#key("p") pastes after (a line yanked with #key("x") #key("y") goes in as a
new line 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 a word into it and click it, or delete the
defaults. #key(":") moves the keyboard to the tag, onto its #word("Save")
the first time, in normal mode (#key("Tab") runs it), and back. Any word
runs from any tag: #word("Exit") in a pane's tag quits too. The path
at the start of a pane's tag is computed: typing into it drafts a new name,
#key("Enter") confirms and 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`. Where depends on 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],
)

The keyboard stays where it was. A file's tag runs in the file's directory,
so run project commands (`make`) from a column or the workspace tag, or a
shell. A command pane's tag says `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") stops what pardes started (`Kill make`: those whose line
starts with `make`); #word("Exit") quits pardes. A pane word from a column
tag (#word("Save"), #word("Del")) 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 #btn("B1")-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. A
look moves the keyboard but not the active column: #btn("B3") on a file
already open in another column jumps there, and 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")).

A column can be empty: closing its last pane leaves it. #word("Delcol")
and #word("Joincol") take columns away. Closing the session's last pane
quits pardes.

= Looking <looking>

#btn("B3") (or #key("Enter")) on a path opens it, or goes to the pane that
already shows it; `file:12` goes to line 12, `file:/re/` to the next
match of `re`, and the other address forms are on the cheatsheet.
#key("/"), text and #key("Enter") list the lines holding it in a `+Search`
and go to the first; #keys("n", "N") step through the rest. A directory types `ls` into a terminal idle there,
else opens one there. A URL opens in the browser. A relative path is
looked for in the looking pane's directory, then in the directory of each
pane on the jump list, most recent first.

#word("Find") `name` lists the files below the pane's directory whose
names hold it; #word("Grep") `text` lists the lines that hold the text,
literally (no regular expression), under every pane's directory. Both land
in a `+Search` listing; their limits are in the reference.

= Unsaved panes <unsaved-panes>

A pane with unsaved text is marked on its grip. #word("Del") on it refuses
once: the message row says `1 unsaved pane — Del again to discard` and the
pane is listed in `+Unsaved`. The same #word("Del") again discards it.
#word("Exit"), #word("Restore") and #word("Delcol") refuse once the same
way. A pane with nothing unsaved closes at once. From the keyboard
(#key("SPC d")), #word("Del") between two panes also asks which takes its
rows: #key("k") above, #key("j") below. To quit, press #key("SPC q") or
click #word("Exit") in the workspace tag with #btn("B2"); it refuses once
over unsaved panes too.

= 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; `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.
- `Repl python` in its tag makes #btn("B2") on a `.py` pane send the text
  to that REPL.
- Paged output (`git log`, `man`) opens in a `+Pager` pane (#doc("setup", section: "pager")).

= Reviewing diffs <reviewing-diffs>

Open a `.diff` or `.patch`, or run `git diff` as a command: the output is
drawn as a diff, each hunk coloured in its file's language. #btn("B3") on a
`diff --git`, `---` or `+++` line opens the file; on `@@` the hunk's first
new line; on a hunk line's `+`, `-` or space, that line in the new file.

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

In a pane's shell, `pardes FILE` opens FILE in this session and returns at
once, as acme's `B` does; a FILE not there yet opens an empty pane that
#word("Save") creates. `pardes --wait FILE` returns when that pane is
closed, as acme's `E` does, which makes it an `EDITOR`
(#doc("setup", section: "editor-setup")). Refusals and `--nested` are in
the reference.

= Keys <keys>

Motions select what they cross, and an edit acts on the selection: #key("w")
then #key("d") deletes a word. #key("x") selects lines, #key("v") extends,
#key(";") collapses to the cursor. #key("s") makes a cursor per regex match
and every edit acts at each. #key("/") is a substring search; the regexes
are on #key("s") and #key("S"). #keys("n", "N") step through everything a
look would open, across panes. Line end is #key("g l"). #key("SPC") starts
the leader, #key("SPC ?") lists every path, #word("Help") every key and
builtin, and #word("Tutor") (#key("SPC h t")) practises them. The language
keys (#keys("g d", "g r"), `SPC l`) work once a server is installed
(#doc("setup", section: "language-servers")).

= 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.
#word("Attach") `work` (#key("SPC s a")) switches this window to it, and
#word("Detach") (#key("SPC s D")) leaves it running. Every attached frontend
sees the same screen.

= 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`.