ductus

ductus is a modal terminal editor. This glossary pins down the words that the code, the docs, and conversations use for its domain.

Text

Document: The editor’s copy of the text of one file, together with its Line ending and Revision tree. Avoid: Buffer, file

Grapheme: The smallest unit of text a user sees as one character, such as a letter with its combining marks or a ZWJ emoji. One invalid byte is one Grapheme. Avoid: Character, except in a command name such as move-character-left; glyph

Hunk: One run of lines that differ between an old and a new text: lines added, removed, or changed, with at least one equal line between two Hunks. Avoid: Chunk, change, delta

Line ending: The byte sequence that ends a line in a Document, either LF or CRLF. Avoid: Newline style, EOL

Position: A byte offset into a Document. dk derives char, line, and UTF-16 offsets from it. Avoid: Index, cursor position

Editing

Block mode: The Mode that keeps a block: the rectangle between two corners, the anchor corner and the cursor corner. Each line of the block that reaches its left side gets one Range. A motion moves the cursor corner, and the Ranges follow the block. Most other keys of Select mode act on the Ranges, and then the editor goes back to Normal mode. Avoid: Visual block, column mode, rectangle selection

Jump: A place to go back to: a Document and the Selection in it. An edit moves a Jump with its text. Avoid: Mark, bookmark, location

Jumplist: The Jumps of one View, oldest first, that C-o steps back through and C-i steps forward through. A command that moves far, such as gg or gd, adds the place it leaves. Avoid: History, back stack

Mode: The state of the editor that decides what a key does: Normal, Insert, Select, or Block mode. Each Mode has its own table of keys. Avoid: State, layer

Range: One anchor and head pair of Positions. The anchor stays put and the head moves. A Range always covers at least one Grapheme. Avoid: Cursor, region

Register: A named store of text values, one value for each Range, that a yank writes and a paste reads, such as ", the default, or +, the system clipboard. Avoid: Buffer, kill ring

Selection: The sorted, non-overlapping set of Ranges on one (Document, View) pair, with one Range marked primary. Avoid: Cursors, multi-cursor

Tab page: A set of Views that fill the screen together, and the one of them that has the focus. Only one Tab page shows at a time. A Document belongs to no Tab page, so Views of two Tab pages can show the same Document. Avoid: Tab, except in a command name such as goto-next-tab; workspace, layout

Text object: A part of the text around a Range that a key names, such as a word, a pair of brackets, or a function, which a command selects inside or around. Avoid: Object, motion

Transaction: A set of changes to a Document, checked against the length of the Document it applies to. Avoid: Edit, patch, diff

View: One window onto a Document, with its own Selection and scroll position. Views share the screen, side by side or one above the other. Splitting a View adds a second View onto the same Document. Avoid: Pane, split, window

Rendering

Annotation: Text that a View draws next to or over a Document but that is not in the Document, anchored to a Position and mapped through each Transaction. Avoid: Ghost text, virtual text, decoration

Catalog: The table of one Locale that gives the text of each Phrase. The English Catalog is complete, and the Catalog of another Locale may leave a Phrase out. Avoid: Dictionary, resource bundle, translation file

Diff session: Two Views whose Documents are compared line by line, with their rows lined up so that each equal line is on the same row in both Views. Avoid: Diff mode, diff view

Grammar: A tree-sitter parser for one language, fetched from a source pinned to one commit, or read from one of the user’s directories, and built into a shared object that dk loads to highlight a Document. Avoid: Parser, syntax, language

Highlight query: A tree-sitter query, highlights.scm, that names a Style scope for each node of a Grammar that it captures. Avoid: Syntax file, highlight rules

Locale: The human language, and the region when it matters, that dk writes its Phrases in. It comes from a setting of the user, or from the environment of the user when no setting says otherwise. Avoid: Language (that word names a programming language in dk), lang

Message: Text that the last row showed, with its time and its kind: error, warning, or info. :show-messages lists the Messages of the session, oldest first. Avoid: Log, notification, toast

Phrase: A stable key with named arguments, which the Catalog of a Locale turns into text. When the last row shows the text of a Phrase, the text becomes a Message. A command description and an option doc are Phrases too. Avoid: String, i18n string, message key

Picker: A box that lists items, such as files, Documents, or commands, filters them by a query that the user types, and acts on the item that the user picks. Avoid: Finder, fuzzy finder

Popup: A box next to the cursor of the focused View that shows text from a Language server, such as hover text or signature help, one entry at a time. It does not take the focus: a key that it does not use goes to the editor. Avoid: Tooltip, overlay, window

Style scope: A theme key, such as ui.text or ui.statusline, that a draw call looks up to get its style. A missing scope falls back to its parent. Avoid: Highlight group, color key

Visual column: The column of a cell in a View, counted in terminal cells, including the width of tabs and of inline Annotations. It counts from the start of its Visual line. Avoid: Display column, screen column

Visual line: One row of a View that draws part of a text line, or all of it. A text line that is not wrapped is one Visual line. Avoid: Display line, screen line, wrapped line

Wrap: The break of a text line into Visual lines, so that no Visual line is wider than the View. Avoid: Line wrap, word wrap

History

Backup: The text of a Document with unsaved changes, which dk writes to the state directory when it panics. Avoid: Swap file, recovery file

Change: One change in the version control of a workspace, as a vcs plugin reports it, with its id: the change id of jj, or the commit id of a vcs that has no other id. Avoid: Commit, Revision

History: The Revision tree of one Document, with its current Revision and its Save markers. Avoid: Undo stack, undo list

Revision: One node in the Revision tree: the Document state after one committed Transaction. Avoid: Undo step, version

Revision tree: Every Revision of a Document, where an edit after an undo starts a new branch and no Revision is ever lost. Avoid: Undo stack

Save marker: The record that a Revision was written to disk, which lets you move through history by save count. Avoid: Checkpoint

Undofile: The Revision tree of a Document, stored on disk so that undo survives a restart. Avoid: Undo cache, swap file

Plugins

Capability: A permission, granted in user config, for a Plugin to reach the filesystem, processes, or the network. Avoid: Permission, scope

Default plugin: A Plugin that ships with ductus and provides a standard feature, such as the keymap, the motions, or the jj vcs plugin. It has no more trust than any other Plugin, except that the vcs plugin has a default exec grant for jj (ADR 0007). Avoid: Built-in, core plugin

Emergency mode: The state the editor enters when the keymap Default plugin fails, with a minimal native keymap that can still type, move, save, and quit. Avoid: Safe mode, fallback mode

Hook: A named editor event that a Plugin can subscribe to, such as a Document being opened or saved. Avoid: Callback, listener

Plugin: A WebAssembly component that extends the editor through the public editor API. Avoid: Extension, script, addon

Runtime directory: The directory of the files that ductus ships beside its binary, such as themes. It is <prefix>/share/ductus/runtime, or $DUCTUS_RUNTIME. It is part of the install and never part of a workspace. Avoid: Data directory, share directory

Trusted workspace: A workspace that the user has approved, so that its .ductus/ config applies like user config, and a granted Plugin can use its Capability there (ADR 0007). The workspace need not have a .ductus/, such as a jj repository with no ductus config. Avoid: Safe directory, allowed project

User plugin: A Plugin from plugins/*.wasm in the user config directory, other than keymap.wasm and vcs.wasm.

Language servers

Diagnostic: A Language server’s message about a Range of a Document, such as an error, with its severity. dk shows it at the end of its line and in the style of its severity, and an edit moves it with the text. Avoid: Lint, problem

Language server: A program that knows a language and talks to dk over stdio with the Language Server Protocol. A [language-server.<name>] table of languages.toml defines it, and a language names its servers. dk starts one only in a Trusted workspace. Avoid: LSP, client

LSP root: The directory that a Language server runs in and gets as its root: the topmost directory, from the file up to its workspace, that contains a marker of roots, or else the workspace. Avoid: Project root