klammertext/doc/edit/notepadpp/README.md

# Klammertext support for Notepad++

Notepad++ support for editing Klammertext files (`.kt` documents and `.k`
klammer definitions): syntax highlighting through a **User Defined
Language**, and the shared editor core's delimiter check and
reindentation through two **Run-menu commands**. Notepad++ is Windows
only, and so is this package.

Notepad++ has no Python plugin host and no built-in language-server
client, so it cannot import the shared core the way Sublime Text does or
talk to the language server the way VS Code does. What it has is a
declarative highlighter and a Run menu that can invoke any program on the
current file, and this package uses exactly those two things.

## Files

| File | Purpose |
|---|---|
| `Klammertext.udl.xml` | The User Defined Language: highlighting for the three `@`-tiers, escapes, text removal, and the `@code` verbatim interior. Its header lists what it colours and the limits of a UDL. |
| `klammertext_edit.py` | The shared editor core (in the editing zip it sits here; in the Klammertext repository it is `doc\edit\shared\klammertext_edit.py`). The Run commands call it. |
| `README.md` | This file. |

## Requirements

- Notepad++ 7.9 or later (the `userDefineLangs` folder; any recent
  version qualifies).
- For the Run commands: `python` on the `Path` -- Python for Windows
  from python.org, with "Add python.exe to PATH" selected. The commands
  are Python and do not need Klammertext itself, which on Windows lives
  in WSL (the install page `windows_wsl_install.md`); a file there is opened
  through `\\wsl.localhost\Ubuntu\...`.
- Files saved as UTF-8 (Notepad++'s default for new files; **Encoding ￫
  Convert to UTF-8** for an older one). Line endings do not matter, and
  a file in another encoding is refused by `ktext` with the remedy named.

## Install the highlighting

Copy `Klammertext.udl.xml` into Notepad++'s user-defined-language folder
and restart Notepad++:

```powershell
$d = "$env:AppData\Notepad++\userDefineLangs"
New-Item -ItemType Directory -Force $d | Out-Null
Copy-Item Klammertext.udl.xml $d
```

Notepad++ loads every file in that folder at start. `.kt` and `.k` files
then open as "Klammertext" (the language shows in the status bar and at
the bottom of the **Language** menu). The alternative is the dialog:
**Language ￫ User Defined Language ￫ Define your language… ￫ Import…**,
which copies the file to the same place.

What you see: klammer applications (`@name … @`) in blue, definitions
(`@@name … @@`) in green, system commands (`@@@name … @@@`) in orange;
a `#` at the start of a line greys the rest of the line, `#[ … ]#` greys
and folds a region; `##`, `#-`, `#+`, `#/`, `|` and `:` in the marker
red; the interior of `@code … code@` muted and uninterpreted. The
colours are the palette's light-ground values with transparent
backgrounds, so a dark theme keeps its own ground.

Two limits, both properties of a UDL rather than of Klammertext, are
documented in the file's header: a `#` that is not the first thing on
its line is not treated as a comment (so that the whitespace operators
`#-`, `#+`, `#/` never grey the rest of their line), and `@c … c@` is not
made verbatim (a UDL delimiter has no word boundary, so `@c` would also
open at `@caption` and `@cond`).

## The Run commands

The shared core's command-line interface reads a file on standard input
and writes the result on standard output; Notepad++'s **Run ￫ Run…**
dialog (`F5`) runs a command line with the current file's path filled in
as `$(FULL_CURRENT_PATH)`. Two commands cover the structural tools.
Replace `C:\Users\<you>\klammertext\doc\edit\shared` with the folder that
holds `klammertext_edit.py` (with the editing zip, the folder this
README is in).

**Check the delimiters** — lists every unclosed opening, extra close,
name or tier mismatch, and unclosed literal span or `#[` block, as
`line:column: message`; an empty window means the file is balanced.
The `/k` keeps the window open to read:

```
cmd /k python "C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py" check < "$(FULL_CURRENT_PATH)"
```

**Reindent the file** — rewrites the file with the canonical
indentation (2 spaces per nesting level, bars and closes at their
opener's column, `@document` transparent, verbatim and removed text
untouched):

```
cmd /c python "C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py" indent < "$(FULL_CURRENT_PATH)" > "$(FULL_CURRENT_PATH).tmp" && move /y "$(FULL_CURRENT_PATH).tmp" "$(FULL_CURRENT_PATH)"
```

Paste each line into the Run dialog once, press **Save…**, give it a
name ("Klammertext check", "Klammertext reindent") and a shortcut
(`Ctrl+Alt+K`, `Ctrl+Alt+I` are free); they then appear at the bottom of
the **Run** menu with those keys.

Two things to know about the reindent command. It works on the file
**on disk**, so save first (`Ctrl+S`); Notepad++ does not save before
running. And after it runs, Notepad++ notices the changed file: with the
default setting it asks whether to reload, which you answer Yes; under
**Settings ￫ Preferences ￫ MISC. ￫ File Status Auto-Detection** the
choice "Update silently" makes the reload automatic. Undo history is
lost on a reload, as for any external edit.

Table alignment and jump-to-match need a caret position the Run dialog
cannot pass, so they are not offered here. They are available in every
other supported editor, and for Notepad++ through the PythonScript
plugin, which embeds a Python that can import the shared core and reach
the caret; a script for it is a possible addition, not part of this
package.

## Keeping things in sync

The UDL restates the literal-klammer set (`@code`) that the shared core
owns in `LITERAL_KLAMMERS`; its header says how to add one. The editor
support's overview is `doc/edit/README.md` in the Klammertext repository.