klammertext/doc/edit/vim/README.md

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 — on Windows python, the name python.org installs (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 (on Windows python).

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; on Windows python)
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:

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.