Andy Kopra
2eb16791d2
Folder copies into ~/.vscode/extensions no longer load in modern VS Code; make_vsix.sh packages the extension (bash + python3 only) and the README installs it with `code --install-extension`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# Klammertext support for Visual Studio Code
|
|
|
|
VS Code support for editing Klammertext files (`.kt` documents and `.k`
|
|
klammer definitions): syntax highlighting, delimiter matching and jumping,
|
|
structural reindentation, table alignment, and delimiter diagnostics in the
|
|
Problems panel.
|
|
|
|
The extension has **no npm dependencies and no build step**. Highlighting
|
|
is a TextMate grammar (converted from the Sublime Text syntax); everything
|
|
structural comes from the **Klammertext language server**
|
|
(`klammertext_ls.py`), a dependency-free Python process the extension
|
|
spawns, which itself runs the shared editor core (`klammertext_edit.py`)
|
|
used by the Sublime Text and Vim integrations. One implementation of the
|
|
language's structure, everywhere.
|
|
|
|
## Requirements
|
|
|
|
- VS Code 1.75 or later — a minimum, not a target: VS Code's monthly
|
|
releases count 1.75, 1.76, … (1.75 is from January 2023), so any
|
|
version from the last few years qualifies.
|
|
- `python3` on `PATH` (or set `klammertext.pythonPath`); Klammertext itself
|
|
already requires Python.
|
|
- The language server, found automatically in this order:
|
|
1. the `klammertext.serverPath` setting, if set;
|
|
2. `klammertext_ls.py` vendored next to `extension.js` (the layout the
|
|
Klammertext editing zip ships);
|
|
3. `../shared/klammertext_ls.py` relative to the extension directory (the
|
|
layout of the Klammertext repository — using the extension straight
|
|
from a checkout just works);
|
|
4. `$KLAMMERTEXT_HOME/doc/edit/shared/klammertext_ls.py`.
|
|
|
|
## Install
|
|
|
|
Package the extension as a `.vsix` and install it (the builder needs only
|
|
bash and python3; the editing zip from the Klammertext website ships a
|
|
prebuilt `klammertext.vsix`, so there the first step is already done):
|
|
|
|
./make_vsix.sh
|
|
code --install-extension klammertext.vsix
|
|
|
|
then restart VS Code (or run the **Developer: Reload Window** command).
|
|
`make_vsix.sh` vendors the shared core and the language server into the
|
|
package automatically, from this folder or from `../shared/`.
|
|
|
|
Do **not** copy this directory into `~/.vscode/extensions/` by hand:
|
|
modern VS Code loads only *registered* extensions, so a merely copied
|
|
folder is silently ignored (and flagged for deletion in that directory's
|
|
`.obsolete` file). Installing the `.vsix` is what registers it.
|
|
|
|
**Note:** `.kt` is also Kotlin's extension. Stock VS Code has no Kotlin
|
|
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
|
|
|
|
**Syntax highlighting** — the same token classes as the Emacs, Sublime
|
|
Text, and Vim support: text removal (`#`, `##`, nestable `#[ ... ]#`), the
|
|
three `@`-tiers — application (`@`), definition (`@@`), system (`@@@`) —
|
|
each as an opening (`@name`, one unit) or a close (`name@`, bare `@`),
|
|
`^`-escapes, and verbatim `@code ... code@` interiors. Colors come from
|
|
your theme (applications as functions, definitions as types, system
|
|
commands as keywords, removed text as comments). To adopt the full
|
|
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
|
|
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.
|
|
|
|
**Commands and keybindings** (when editing Klammertext):
|
|
|
|
| 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 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 toggling** — `Ctrl+/` toggles `#` line removal and
|
|
`Shift+Alt+A` wraps the selection in `#[ ... ]#`, via the standard VS Code
|
|
comment commands.
|
|
|
|
## Settings
|
|
|
|
| Setting | Meaning (default) |
|
|
|---|---|
|
|
| `klammertext.pythonPath` | Python interpreter for the server (`python3`) |
|
|
| `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |
|