klammertext/doc/edit/vscode/README.md

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

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

**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
(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.

**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.

**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).

**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).

**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.