Andy Kopra
ef77f03584
The @@@klammerset system command formally declares a klammerset — a named, logically related group of klammer definitions — with an operative, idempotent declaration (:requires and :files load in order at the declaration point, relative to the declaring file). A bare symbol given to ktext -k, kdesc --input, or :requires resolves to x/x.k on the search path: the document's directory, then KLAMMERTEXT_KLAMMERSETS, then KLAMMERTEXT_HOME; kdesc --klammerset lists the available sets. sks/sks.k is the first declared klammerset, so `-k sks` loads the SKS by name. The engine's lookup classes were renamed *_set → *_registry to keep the two concepts apart, and the whole C++ tree now follows standard const-correctness conventions. tst/ gains klammerset_test.sh (18 cases). (from dev 64b1abf23e56)
216 lines
12 KiB
Markdown
216 lines
12 KiB
Markdown
# Klammertext for Sublime Text
|
||
|
||
A Sublime Text package for Klammertext: syntax highlighting, delimiter
|
||
matching, comment toggling, reindentation, and table alignment for `.kt` and
|
||
`.k` files. The structural features run on the **shared editor core**
|
||
(`klammertext_edit.py`) — the single Python implementation used by the Vim
|
||
and VS Code integrations and the Klammertext language server — so all the
|
||
editors behave identically; the plugin files here are Sublime command
|
||
wrappers. Behavior mirrors the Emacs mode closely (an independent elisp
|
||
implementation, held equal by the Klammertext test suite); where the two
|
||
intentionally differ, the file headers say so.
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `Klammertext.sublime-syntax` | Syntax highlighting. Colors the text-removal constructs (`#`, `##`, `#[...]#`) and the three `@`-tiers — application `@`, definition `@@`, system `@@@` — each as an opening vs. a close, plus `^`-escapes and verbatim `@code ... code@` spans. |
|
||
| `Klammertext.py` | Jump between an opening and its close, and live highlighting of the matching delimiter as the caret moves (mismatched or unbalanced delimiters flag in red). Both reuse the shared core's context-sensitive matcher. |
|
||
| `Klammertext_indent.py` | **Experimental.** Reindentation per the Klammertext convention (see below). A separate unit: delete this one file to disable indentation; nothing else is affected. |
|
||
| `Klammertext_align.py` | **Experimental.** Table alignment (see below). Also a separate, deletable unit. |
|
||
| `klammertext_edit.py` | The shared editor core the three plugins import. Ships in the editing zip; when you install from the Klammertext repository instead, copy it in from `doc/edit/shared/` (or leave the package inside the repository tree, where the plugins find `../shared/` themselves). |
|
||
| `Default.sublime-keymap` | Binds jump-to-match to **Ctrl+M**, reindent to **Ctrl+Alt+I**, and table alignment to **Ctrl+Alt+A**, scoped to Klammertext files. |
|
||
| `Comments.tmPreferences` | Comment toggling: **Ctrl+/** inserts `# ` (line removal), **Ctrl+Shift+/** wraps in `#[ ... ]#` (block removal). |
|
||
| `Breakers` / `Celeste` / `Mariana` / `Monokai` / `Sixteen` `.sublime-color-scheme` | Color overrides for Sublime's five built-in schemes — one hue system, full intensity on the dark schemes, scaled down on the light ones. Additive: they recolor only the Klammertext delimiters and leave the rest of each scheme unchanged. |
|
||
| `README.md` | This file. |
|
||
|
||
## Installation
|
||
|
||
Put the files into a folder named `Klammertext` under Sublime's `Packages`
|
||
directory:
|
||
|
||
| Platform | Path |
|
||
|----------|------|
|
||
| Linux | `~/.config/sublime-text/Packages/Klammertext/` |
|
||
| macOS | `~/Library/Application Support/Sublime Text/Packages/Klammertext/` |
|
||
| Windows | `%AppData%\Sublime Text\Packages\Klammertext\` |
|
||
|
||
The quickest way to find it: **Preferences ￫ Browse Packages…** opens the
|
||
`Packages` directory. Create the `Klammertext` folder there and copy the files
|
||
in. Sublime loads them live — no restart — and applies the syntax to `.kt` and
|
||
`.k` files automatically. The package must include `klammertext_edit.py`
|
||
(see the file table above): the editing zip ships it in place; from a
|
||
repository checkout, copy `doc/edit/shared/klammertext_edit.py` into the
|
||
folder alongside the plugin files.
|
||
|
||
Use a dedicated folder (not `Packages/User/`) so the bundled keymap does not
|
||
merge into your personal one. If you want highlighting only, the
|
||
`.sublime-syntax` file alone works from `Packages/User/`.
|
||
|
||
The plugin targets **Sublime Text 4**: the live-highlight colors use Sublime's
|
||
adaptive `region.*` scopes, which were added in ST4.
|
||
|
||
## Features and keys
|
||
|
||
| Trigger | Action |
|
||
|---------|--------|
|
||
| open a `.kt` / `.k` file | Syntax highlighting (automatic) |
|
||
| **Ctrl+M** | Jump between a klammer application's opening and closing `@` (equivalent of the Emacs mode's `C-c C-j`) |
|
||
| caret on a klammer `@` | The matching delimiter boxes automatically; a name mismatch or unbalanced delimiter boxes in red with a status-bar message (equivalent of `show-paren-mode`) |
|
||
| **Ctrl+/** | Toggle line comment (`#`) |
|
||
| **Ctrl+Shift+/** | Toggle block comment (`#[ ... ]#`) |
|
||
| **Ctrl+Alt+I** | Reindent the selected lines (the current line when there is just a caret) — experimental, see "Indentation" below |
|
||
| **Ctrl+Alt+A** | Align the columns of the table containing the caret — experimental, see "Table alignment" below |
|
||
|
||
Ctrl+M is Sublime's own "go to matching bracket" key, reused here because the
|
||
built-in cannot match Klammertext's context-dependent `@`. macOS users who
|
||
prefer `super+m` can change it in `Default.sublime-keymap`.
|
||
|
||
## Indentation (experimental)
|
||
|
||
`Klammertext_indent.py` ports the Emacs mode's indentation
|
||
(`doc/edit/emacs/klammertext-indent.el`): **Ctrl+Alt+I** reindents the line(s)
|
||
touched by the selection to reflect the klammer nesting, two spaces per level:
|
||
|
||
```
|
||
@ol
|
||
Item one
|
||
| Item two
|
||
@ol
|
||
Embedded item one
|
||
| Embedded item two
|
||
@
|
||
| Item three
|
||
@
|
||
```
|
||
|
||
The rule: a line indents to 2 × depth; a line *beginning* with a bar run
|
||
(`|`, `||`, …) or a closing delimiter sits one level less — at its owner's
|
||
opening column, so bars and closes line up under the `@` of the klammer they
|
||
belong to. All three `@`-tiers indent uniformly. Exceptions: `@document`
|
||
contributes no level (a document's paragraphs stay at the left margin); lines
|
||
inside verbatim `@code` content, inside `@eval` argument spans (inline Python
|
||
is indentation-sensitive), and inside removed regions are never touched. The
|
||
policy lists (`TRANSPARENT_KLAMMERS`, `CODE_KLAMMERS`, `INDENT_OFFSET`) are
|
||
in the shared core (`klammertext_edit.py`), kept in sync with the Emacs
|
||
defcustoms.
|
||
|
||
Sublime's own Reindent (Edit ￫ Line ￫ Reindent) is driven by single-line
|
||
regex patterns that cannot express Klammertext nesting, so this is a plugin
|
||
command instead. Nothing reformats automatically (no on-Enter auto-indent):
|
||
whitespace is content in Klammertext, so indentation happens only when you
|
||
ask for it. To disable the feature, delete `Klammertext_indent.py` and the
|
||
Ctrl+Alt+I entry in `Default.sublime-keymap` (or just the keymap entry, to
|
||
keep the command available from plugins).
|
||
|
||
## Table alignment (experimental)
|
||
|
||
`Klammertext_align.py` ports the Emacs mode's table alignment
|
||
(`doc/edit/emacs/klammertext-align.el`): **Ctrl+Alt+A** with the caret anywhere
|
||
inside a `@table` span pads the cells of its rows so the `|` separators line
|
||
up:
|
||
|
||
```
|
||
@table
|
||
First item | Second | A third item that's longer ||
|
||
Row 2 | Text | Not as long ||
|
||
@
|
||
```
|
||
|
||
A row is one line ending with the row delimiter `||` (the customary trailing
|
||
delimiter; the last row may omit it). Alignment is for small data items, so
|
||
a row is left untouched — and contributes nothing to the column widths —
|
||
when any of its cells is longer than `CELL_MAX` (30) characters or the row
|
||
spans lines. If the aligned rows would exceed `ROW_MAX` (100) columns,
|
||
nothing changes and the status bar says so. The padding is semantically
|
||
free: the SKS strips cell content, no whitespace is ever inserted inside a
|
||
bar run (which would turn a `||` row separator into an empty `| |` cell),
|
||
and bars inside a nested klammer in a cell (`@frac 1 | 2 @`) belong to that
|
||
klammer, not the table. Aligned rows adopt the leading whitespace of the
|
||
first aligned row — run Ctrl+Alt+I first if the rows disagree. The limits
|
||
(`ALIGN_KLAMMERS`, `CELL_MAX`, `ROW_MAX`) are in the shared core
|
||
(`klammertext_edit.py`), mirrored from the Emacs defcustoms.
|
||
|
||
## Colors
|
||
|
||
Colors are installed automatically for all five of Sublime's built-in schemes.
|
||
Each `*.sublime-color-scheme` file (Breakers, Celeste, Mariana, Monokai,
|
||
Sixteen) is an *additive override*: Sublime merges it onto the matching scheme
|
||
by filename, recoloring only the Klammertext delimiters and leaving everything
|
||
else untouched. There is nothing to set up.
|
||
|
||
All five share one hue system — application blue, definition green, system
|
||
orange, each opening bright and its close the same hue darker — shown at full
|
||
intensity on the dark schemes (Monokai, Mariana) and scaled down for contrast on
|
||
the light schemes (Breakers, Celeste, Sixteen). Removed text uses each scheme's
|
||
own comment grey.
|
||
|
||
For any other scheme — a legacy `.tmTheme` such as Solarized, or a third-party
|
||
scheme — copy one of the included files to `<Scheme Name>.sublime-color-scheme`
|
||
in the package folder (its name is shown at **Preferences ￫ Settings** under
|
||
`color_scheme`), choosing a light or dark source file to match the ground. The
|
||
exact values are in each file's header comment.
|
||
|
||
## Sublime Merge
|
||
|
||
Sublime Merge reads the same `Packages` directory as Sublime Text, so the
|
||
package installed above needs no separate installation: `.kt` and `.k` files
|
||
are syntax-highlighted in Merge's diffs, and an edit to the syntax file is
|
||
picked up live, exactly as in the editor.
|
||
|
||
Only the syntax file crosses over. Merge has no Python plugin host — it
|
||
ships no `plugin_host` binary — so none of this package's code runs there:
|
||
|
||
| File | In Sublime Merge |
|
||
|------|------------------|
|
||
| `Klammertext.sublime-syntax` | Works. Delimiters and removed text are colored in diffs. |
|
||
| `Klammertext.py`, `Klammertext_indent.py`, `Klammertext_align.py` | Do not run: no plugin host. |
|
||
| `Default.sublime-keymap` | Inactive — it binds plugin commands. |
|
||
| `Comments.tmPreferences` | Inactive — Merge does not edit text. |
|
||
| `Breakers` / `Celeste` / `Mariana` / `Monokai` / `Sixteen` `.sublime-color-scheme` | Not used. They override Sublime Text's built-in schemes by name; Merge has its own. |
|
||
|
||
So delimiter matching — **Ctrl+M** and the live highlight of the matching
|
||
delimiter — is a Sublime Text feature only. Merge colors the delimiters but
|
||
cannot match them: matching is context-sensitive code, not a syntax rule
|
||
(which is why it is a plugin in the first place). Merge's built-in bracket
|
||
matching does not stand in for it either; that matches literal `(`, `[`, `{`
|
||
characters, not `@name ... name@` runs.
|
||
|
||
Merge colors the Klammertext scopes with its own scheme, so the hues differ
|
||
from the editor's — the token classes are distinguished, but the package's
|
||
five color schemes do not apply.
|
||
|
||
## Keeping literal klammers in sync
|
||
|
||
Klammers whose content is verbatim (`@code ... code@`) are listed in the
|
||
shared core — `LITERAL_KLAMMERS` in `klammertext_edit.py`, the source of
|
||
truth — and restated in the static per-editor artifacts, which cannot read
|
||
Python:
|
||
|
||
- the `@code` rule and `literal_code` context in `Klammertext.sublime-syntax`
|
||
- `klammertext-literal-klammers` in `doc/edit/emacs/klammertext-mode.el`
|
||
(the independent elisp implementation)
|
||
- the `@code` region in `doc/edit/vim/syntax/klammertext.vim` and the rule
|
||
in `doc/edit/vscode/syntaxes/klammertext.tmLanguage.json`
|
||
|
||
All are seeded with just `code`. When you add or remove a literal klammer,
|
||
change them together.
|
||
|
||
## Not included
|
||
|
||
Whole-file diagnostics (persistent error underlines when the cursor is
|
||
elsewhere) are not part of this package, but they exist: the **Klammertext
|
||
language server** (`doc/edit/shared/klammertext_ls.py`, the same program the
|
||
VS Code extension uses) serves them to Sublime through the community LSP
|
||
package. Install "LSP" from Package Control and add a client with
|
||
`command: ["python3", "/path/to/klammertext_ls.py"]` for the
|
||
`text.klammertext` selector. Everything in this package works the same
|
||
with or without it.
|
||
|
||
## Troubleshooting
|
||
|
||
If the plugin does not seem to load, open **View ￫ Show Console** for any error
|
||
message. Check that the files sit directly inside `Packages/Klammertext/` (not
|
||
a nested subfolder) and that the current file's syntax reads "Klammertext" in
|
||
the status bar at the bottom-right of the window.
|