ack
32aa47d41c
Klammertext on Windows is the Linux build inside WSL 2, or the prebuilt containers through Docker Desktop. The native build from source (MSYS2) is no longer offered: - doc/install/windows_source_install.md and the bundled shell under win/ are removed. - doc/install/windows_wsl_install.md is the Windows page. It says there is no native build, and its editor section says what holds for each editor: Emacs, Vim and Visual Studio Code (through its WSL extension) as on Linux; Sublime Text and Notepad++ on the Windows side, with their self-contained packages, on files opened through \\wsl.localhost. - The README lists six install guides; the Notepad++ and VS Code READMEs no longer refer to the MSYS2 shell. No change to the language, the Standard Klammer Set or the commands.
155 lines
8.0 KiB
Markdown
155 lines
8.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` — on Windows `python`, the name python.org installs
|
|
(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 Python — on Windows, run it at the Linux prompt of WSL, where
|
|
Klammertext is installed; 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`
|
|
(on Windows `python`) 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`; on Windows `python`) |
|
|
| `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |
|
|
|
|
`pythonPath` matters when the interpreter 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.
|