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

pardes is a screen of columns. Each column holds panes, and each pane is a
tag (a line of words) over a body: a file, a terminal, a PDF or an image.
Above the columns runs the workspace tag, and each column has a tag of its
own. Any text anywhere can be clicked: #btn("B2") runs it, #btn("B3") looks
at it. The keys are helix's, in modes.

= Words you'll see <words>

#pairs(
  [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],
  [active column], [where the next new pane goes (below)],
  [command pane], [a terminal that runs one command line and shows its output],
  [scratch], [a pane of text with no file yet, `+New`],
  [listing], [a pane of places to visit: `+Search`, Recent, Jumplist, Themes],
  [message row], [the line where pardes says what happened],
  [grip], [the box left of a pane's tag: drag it, and it marks unsaved text],
)

= 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.],
)

"The previous pane" is the last other pane on the jump list, else the next
pane down its column. 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, the line, or up to the matching bracket or quote.],
  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. The chords are on the
cheatsheet.

= 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 between a body and its tag. 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 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, and the other address forms
are on the cheatsheet. 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. From the keyboard (#key("SPC d")), #word("Del") between two panes
also asks which takes its rows: #key("k") above, #key("j") below.

= Terminals <terminals>

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

- `Tty+bash` opens another terminal on that shell; bare #word("Tty") runs
  the #word("Shell") setting.
- #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 pardes
```

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