# Klammertext support for Vim

Vim support for editing Klammertext files (`.kt` documents and `.k` klammer
definitions): syntax highlighting, delimiter matching and jumping, structural
reindentation, table alignment, and a delimiter checker.

The structure-aware features are thin wrappers around the **shared editor
core** (`klammertext_edit.py`) — the single Python implementation of
Klammertext's structural layer used by the Sublime Text and VS Code
integrations and by the Klammertext language server.  The Vim plugin runs it
through `python3`; there is no Vim-specific reimplementation to drift out of
sync.

## Requirements

- Vim 8+ (or Neovim) with `+eval` — any normal Vim; only `vim-tiny` lacks it.
- `python3` on `PATH` (Klammertext itself already requires Python).
- The shared core, found automatically in this order:
  1. `g:klammertext_edit_py`, if you set it (a full path to
     `klammertext_edit.py`);
  2. a `klammertext_edit.py` vendored at this plugin's root (the layout the
     Klammertext editing zip ships);
  3. `../shared/klammertext_edit.py` relative to the plugin directory (the
     layout of the Klammertext repository — using the plugin straight from a
     checkout just works);
  4. `$KLAMMERTEXT_HOME/doc/edit/shared/klammertext_edit.py`.

## Install

Copy (or symlink) this `vim/` directory into a Vim native package path,
renaming it as you like:

    mkdir -p ~/.vim/pack/klammertext/start
    cp -R vim ~/.vim/pack/klammertext/start/klammertext

(Neovim: `~/.local/share/nvim/site/pack/klammertext/start/klammertext`.)
If you copy the directory out of the Klammertext tree, also copy
`shared/klammertext_edit.py` into the copied folder's root — or set
`g:klammertext_edit_py`.  The editing zip from the Klammertext website ships
the vendored copy already in place.

`.kt` and `.k` files then get the `klammertext` filetype.  **Note:** `.kt`
is also Kotlin's extension, and stock Vim maps it to Kotlin; this plugin's
`ftdetect` overrides that unconditionally.  If you edit both languages, see
the comment in `ftdetect/klammertext.vim`.

## What you get

**Syntax highlighting** — the same token classes and palette as the Emacs
and Sublime Text support: text removal (`#`, `##`, nestable `#[ ... ]#`),
the three `@`-tiers — application (`@`, blue), definition (`@@`, green),
system (`@@@`, orange) — each as an opening (`@name`) or a close (`name@`,
bare `@`), opens bright and closes the same hue darker; `^`-escapes;
verbatim `@code ... code@` interiors.  All groups are `hi def` — override
them with `:highlight` in your vimrc.

**Commands** (buffer-local; default mappings below):

| Command | Does |
|---|---|
| `:[range]KlammertextReindent` | reindent the range (default: whole buffer) |
| `:KlammertextAlign` | align the `@table` enclosing the cursor |
| `:KlammertextJumpToMatch` | jump between a klammer application's opening and closing delimiter |
| `:KlammertextCheck` | list unclosed/mismatched delimiters in the location list |

Default mappings (buffer-local; suppress them all with
`let g:klammertext_no_mappings = 1`): `<LocalLeader>i` reindents the current
line (in visual mode, the selection), `<LocalLeader>a` aligns the enclosing
table, `<LocalLeader>j` jumps to the matching delimiter.  `LocalLeader`
defaults to backslash; set `maplocalleader` to taste.

Reindentation is **explicit-only**: whitespace is content in Klammertext,
so nothing reformats as a side effect of typing (`indentkeys` is emptied).
Alignment follows 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.

**With `+python3`** (check `:echo has('python3')`) the shared core also runs
in-process: the `=` operator reindents through `'indentexpr'` (`==`, `gg=G`),
and the matching delimiter is highlighted live as the cursor sits on one —
the show-paren equivalent, with a mismatched or unbalanced delimiter shown
in red plus a message.  Without `+python3` the commands above still work;
they shell out to `python3`.

**Comment toggling** — `'commentstring'` is set to `# %s`, so Vim 9.1's
built-in commenting and Neovim's `gcc`/`gc` (or the commentary plugin)
toggle `#` line removal.

## Configuration

| Variable | Meaning (default) |
|---|---|
| `g:klammertext_edit_py` | full path to `klammertext_edit.py` (auto-detected) |
| `g:klammertext_python` | Python interpreter (`python3`) |
| `g:klammertext_no_mappings` | set to define no default mappings |

## Neovim and the language server

Neovim users can additionally attach Neovim's built-in LSP client to the
Klammertext language server (`klammertext_ls.py`, next to the shared core)
for diagnostics as you type, `gq`/format-document reindentation, and
cursor-hold match highlighting:

```lua
vim.api.nvim_create_autocmd('FileType', {
  pattern = 'klammertext',
  callback = function()
    vim.lsp.start {
      name = 'klammertext-ls',
      cmd = { 'python3', '/path/to/doc/edit/shared/klammertext_ls.py' },
    }
  end,
})
```

The plugin's own commands work the same with or without it.