klammertext/doc/edit/sublime/README.md

# Klammertext for Sublime Text

A Sublime Text port of the Emacs major mode for Klammertext
(`doc/emacs/klammertext-mode.el`).  It brings syntax highlighting, delimiter
matching, and comment toggling to `.kt` and `.k` files.  Behavior mirrors the
Emacs mode closely; 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` | Plugin with two features that share one context-sensitive matcher: 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). |
| `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. |
| `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.

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/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 at
the top of `Klammertext_indent.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/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
sit at the top of `Klammertext_align.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.

## Keeping literal klammers in sync

Klammers whose content is verbatim (`@code ... code@`) are listed in four
places that must agree — a Sublime syntax/plugin cannot read the Emacs
defcustom, so the list is duplicated:

- `klammertext-literal-klammers` in `doc/emacs/klammertext-mode.el` (the source of truth)
- `LITERAL_KLAMMERS` in `Klammertext.py`
- `LITERAL_KLAMMERS` in `Klammertext_indent.py`
- the `@code` rule and `literal_code` context in `Klammertext.sublime-syntax`

All four are seeded with just `code`.  When you add or remove a literal
klammer, change all four.

## Not included

Whole-file semantic validation — persistent error underlines when the cursor is
elsewhere, klammer-name completion, go-to-definition — is not part of this
package.  That would need a language server (used through the Sublime LSP
package), a separate program, and is unrelated to the highlighting and matching
provided here.

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