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

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