diff options
Diffstat (limited to 'docs/tags.md')
| -rw-r--r-- | docs/tags.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 00000000..87cee2ff --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,84 @@ +# Editable tags + +Pardes has three levels of command text: the workspace tag, one tag per +column, and each pane's tag. Column commands run in that column's active +pane (or its first pane when focus comes from another column). This makes +`New`, `Tty`, `Find`, and `Grep` available beside the work they act on. +`New` appears only in the column tag by default; pane tags keep their own +save, terminal, close, and collapse commands. `Tty` opens a new embedded terminal. +Column command text starts flush with the column's left edge, just like the +workspace tag; pane bodies retain their scrollbars and line-number gutters. + +When Look opens the first document and its source column is too narrow for +a new column, it splits below the originating pane, just like `Tty`, instead +of inserting at the top of the leftmost column. The originating terminal is +kept. As with `Tty`, a tagline-only source uses a roomier split parent. + +`Collapse` reduces a pane to just its tagline, giving all its body space to +the nearest expanded pane above, or below if none is above. Other panes keep +their heights. Execute it again to reclaim its former height from that one +neighbor, as far as available space allows. If every pane is collapsed, the +unused area stays blank. +Its text and terminal process are kept; +the command stays available in the visible tag. Every default pane tag includes +`Collapse`, including file, terminal, image, and PDF panes. + +Left-click a tag to place its caret; drag to select text, then type to +replace it. Arrow keys, Home, End, Backspace and Delete edit the line. +Tags reveal the caret horizontally when text is wider than their column. +Escape returns to the body, keeping command-text edits. The existing Exec +and Look gestures still apply; the workspace tag is no longer an inert +left-click target. Pasted text goes to the focused tag, not to the file or +embedded shell beneath it. + +Normal tag navigation now visits pane, column, and workspace tags in order: +from the top pane's `:` tag, `k` reaches the column and another `k` reaches +the workspace; `j` walks back down. Enter or Tab on a header command in +normal mode executes it, as before. `i`/`a`/`I`/`A` switch to editing the +header. In insert mode, Enter is Look and Tab is Exec, as in pane tags. + +Pane filenames and commands now have a single separator space rather than +generated right-alignment padding. Intentionally customized spacing is kept. + +## File names + +Editing a file pane's name creates a draft. Enter confirms the new buffer +name; Escape or leaving the tag cancels the draft. Confirmation changes the +buffer's save target and marks it unsaved. It does **not** rename, create or +overwrite a disk file. A subsequent explicit `Save` writes the buffer to its +committed name. Executing a pane-tag command confirms a valid name draft +first, so a visible draft cannot silently save to the previous name. + +Terminal working directories and generated image/PDF status remain managed +by their corresponding commands. Their command tails are editable just like +file command tails. + +PDF tags follow the same filename-first layout: `manual.pdf [1/12] Tty Del +PdfSections PdfTint Collapse`. Sections and tint commands remain in the editable +tail, without displaying the current tint state. `PdfFit` (`SPC t z`) remains +available, as do the shortcuts for `PdfTint` (`SPC t i`) and `PdfSections` +(`SPC t s`, or `f` on a PDF). + +Terminal tags include `Togglettymode`, which toggles between normal editor mode and raw +terminal input using the same transition as Ctrl-B. It also works while editing +the tag: the command leaves tag editing and toggles the parked body mode. +Executing it on a non-terminal pane does nothing. + +## Saved workspaces + +`Dump` and `Restore` preserve customized workspace and column tags, including +intentionally empty tags. New columns start with the standard column tag. +Closing a column keeps surviving columns' tags; `Joincol` keeps the destination +column's tag. Old dumps without these optional fields retain the defaults. +The automatic `Restore` shortcut does not overwrite a customized workspace +tag. + +The column row stays above panes with `TagBottom` enabled. On screens shorter +than three rows it is omitted so a pane still has room. SDL and TTY share the +same tag text, editing and layout; SDL additionally uses compact font sizing +and subtle pixel separators. + +`ColumnTags` toggles the column row (on by default) without deleting its text. +`FocusTint` controls active-column and active-pane emphasis. SDL also honors +the shared bold, underline, and strikethrough attributes, including diagnostic +underlines and the optional `SyntaxBold` keyword weight. |