VS Code: decoration-based matching, Ctrl+K bindings, README overhaul (from dev f8451715e657)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -52,7 +52,23 @@ support built in, so there is no conflict out of the box; if you install a
|
||||
Kotlin extension, the two will contend for `.kt` and you can decide per
|
||||
file with the language-mode picker (or `files.associations`).
|
||||
|
||||
## What you get
|
||||
## VS Code commands for Klammertext
|
||||
|
||||
| Command | Menu | Key | Cursor position |
|
||||
| --- | --- | --- | --- |
|
||||
| Format Document | Right-click | `Ctrl+Shift+I` | Anywhere in the document |
|
||||
| Format Selection | Right-click | `Ctrl+K Ctrl+F` | Lines selected |
|
||||
| Toggle Line Comment | Edit menu | `Ctrl+/` | In the line to remove with `#` |
|
||||
| Toggle Block Comment | Edit menu | `Ctrl+Shift+A` | Region to remove selected (`#[ ... ]#`) |
|
||||
| Klammertext: Jump to Matching Delimiter | Right-click | `Ctrl+K J` | On the opening `@name` or the closing `name@` / `@` |
|
||||
| Klammertext: Align Table | Right-click | `Ctrl+K A` | Anywhere inside the `@table` |
|
||||
| Delimiter diagnostics | Problems panel | — | Automatic, as you type |
|
||||
|
||||
All commands are also in the Command Palette (`Ctrl+Shift+P`). Keys shown
|
||||
are the Linux defaults: the Klammertext commands use `Cmd+K` on macOS, and
|
||||
the built-in formatting and comment keys differ per OS.
|
||||
|
||||
## Features
|
||||
|
||||
**Syntax highlighting** — the same token classes as the Emacs, Sublime
|
||||
Text, and Vim support: text removal (`#`, `##`, nestable `#[ ... ]#`), the
|
||||
@@ -65,42 +81,71 @@ Klammertext palette (application blue / definition green / system orange,
|
||||
opens bright and closes darker), add `editor.tokenColorCustomizations`
|
||||
rules for the `*.klammertext` scopes in your settings.
|
||||
|
||||
**Diagnostics** — unclosed and mismatched delimiters appear in the
|
||||
Problems panel as you type.
|
||||
|
||||
**Formatting** — **Format Document** / **Format Selection** reindent
|
||||
structurally (2 spaces per nesting level; bar runs and closing delimiters
|
||||
sit at their opener's column; `@document` content stays at the margin;
|
||||
verbatim `@code` interiors, `@eval` code, and removed text are never
|
||||
touched). Reindentation is **explicit-only**: there is deliberately no
|
||||
**Structural reindentation** — Format Document and Format Selection
|
||||
reindent per the Klammertext convention: 2 spaces per nesting level; a
|
||||
line beginning with a bar run or a closing delimiter sits at its opener's
|
||||
column; `@document` content stays at the margin; verbatim `@code`
|
||||
interiors, `@eval` code, and removed text are never touched.
|
||||
Reindentation is **explicit-only**: there is deliberately no
|
||||
format-on-type, because whitespace is content in Klammertext.
|
||||
|
||||
**Delimiter matching** — with the cursor on an application delimiter, the
|
||||
matching delimiter highlights (occurrences highlighting); **Go to
|
||||
Definition** on a delimiter goes to its match. Literal klammers match by
|
||||
name (`@code` ↔ `code@`) with their verbatim content opaque; everything
|
||||
else matches by depth.
|
||||
**Delimiter matching** — with the cursor on an application delimiter
|
||||
(opening `@name`, named close `name@`, or a bare `@` close), the delimiter
|
||||
and its match are boxed; a mismatched named close or an unbalanced
|
||||
delimiter is boxed in **red** with a status-bar message, as in the Emacs,
|
||||
Sublime, and Vim support. **Go to Definition** on a delimiter goes to its
|
||||
match, so Jump to Matching Delimiter has a second home on `F12`. Literal
|
||||
klammers match by name (`@code` ↔ `code@`) with their verbatim content
|
||||
opaque — a stray `@` in the verbatim interior cannot confuse them;
|
||||
everything else matches by depth. Double-click selects a whole delimiter
|
||||
token.
|
||||
|
||||
**Commands and keybindings** (when editing Klammertext):
|
||||
**Delimiter diagnostics** — the automatic Problems-panel entries cover
|
||||
all three `@`-tiers: a closing delimiter with no opening, a named close
|
||||
that disagrees with its opening (`ul@` closing `@ol`), a close of the
|
||||
wrong tier (`@@` closing `@name`), openings never closed, and unclosed
|
||||
`@code` and `#[` regions.
|
||||
|
||||
| Key | Command |
|
||||
|---|---|
|
||||
| `Ctrl+Alt+J` (`Cmd+Alt+J`) | Klammertext: Jump to Matching Delimiter |
|
||||
| `Ctrl+Alt+A` (`Cmd+Alt+A`) | Klammertext: Align Table |
|
||||
**Table alignment** — pads the cells of the `@table` enclosing the cursor
|
||||
so the `|` separators line up, with the rules shared across the editors:
|
||||
rows end with `||`; a row with a cell over 30 characters or spanning lines
|
||||
is left untouched; beyond 100 aligned columns the command declines; bars
|
||||
inside a nested klammer belong to that klammer, not the table; and no
|
||||
whitespace is ever inserted inside a bar run (`||` is a row separator,
|
||||
`| |` an empty cell).
|
||||
|
||||
Table alignment pads the cells of the `@table` enclosing the cursor so the
|
||||
`|` separators line up, with the shared rules: rows end with `||`; a row
|
||||
with a cell over 30 characters or spanning lines is left untouched; beyond
|
||||
100 columns the command declines; bars inside a nested klammer are not
|
||||
separators; no whitespace is ever inserted inside a bar run.
|
||||
**Text removal** — the Toggle Comment commands are VS Code's names; in
|
||||
Klammertext they toggle `#` line removal and `#[ ... ]#` block removal
|
||||
(the `#` does not "comment out": it removes text from processing).
|
||||
|
||||
**Text removal toggling** — `Ctrl+/` toggles `#` line removal and
|
||||
`Shift+Alt+A` wraps the selection in `#[ ... ]#`, via the standard VS Code
|
||||
comment commands.
|
||||
**Keybinding notes** — each Klammertext command has two bindings because
|
||||
some environments never deliver `Ctrl+Alt+letter` chords to VS Code (a
|
||||
right Alt is usually AltGr, not Alt, and some desktops and input methods
|
||||
intercept the chord); the two-step `Ctrl+K` chords go through everywhere.
|
||||
If a key seems to do nothing, run the command from the Command Palette
|
||||
first: if that works, the chord is being intercepted — open **Keyboard
|
||||
Shortcuts** (`Ctrl+K Ctrl+S`), search "klammertext", and rebind.
|
||||
|
||||
## Settings
|
||||
|
||||
A normal installation needs neither setting: the extension runs `python3`
|
||||
from `PATH` and finds the language server automatically (the copy vendored
|
||||
next to `extension.js`, then `../shared/`, then
|
||||
`$KLAMMERTEXT_HOME/doc/edit/shared/`). They exist for unusual setups.
|
||||
Set them in the Settings UI (`Ctrl+,`, search "klammertext") or in
|
||||
`settings.json`; the server is spawned when the extension activates, so
|
||||
reload the window after changing either.
|
||||
|
||||
| Setting | Meaning (default) |
|
||||
|---|---|
|
||||
| `klammertext.pythonPath` | Python interpreter for the server (`python3`) |
|
||||
| `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |
|
||||
|
||||
`pythonPath` matters when `python3` is not on the `PATH` VS Code sees — a
|
||||
VS Code launched from the desktop inherits a different environment than
|
||||
your shell — or when a specific interpreter is wanted. `serverPath`
|
||||
matters only when the server file lives outside the search chain above.
|
||||
If the server cannot be started at all, the extension says so once at
|
||||
activation; highlighting still works, and everything structural
|
||||
(diagnostics, formatting, matching, alignment) waits until the path is
|
||||
fixed.
|
||||
|
||||
Reference in New Issue
Block a user