Windows: product names, the editors, WSL; the Linux page's image step

Assembled from development commit c3c40f6c8fca. Since 830b193: on Windows the products carry Windows names (ktext.exe, klammertext.dll, document.dll, reflect.dll) and the console's output code page is UTF-8 for a run; the editor tooling works on Windows (VS Code, Sublime Text, Vim, with the interpreter's name chosen by platform) and Notepad++ joins it (doc/edit/notepadpp: a User Defined Language and two Run-menu commands); a sixth install page, doc/install/windows_wsl_install.md, for Linux inside WSL; the Windows page opens with the three routes and gains its editor section, the PowerShell quoting and Path notes; the Linux page installs OpenImageIO from the python3-openimageio package and verifies with kdiag --machine; the README lists all six install pages. Linux and macOS behaviour is unchanged.
2026-09-25 18:43:22 +02:00
1 parent 830b19394d
commit ee8bcf5300
@@ -1,7 +1,7 @@
 # Klammertext editor support

 Editing support for Klammertext files (`.kt` documents and `.k` klammer
-definitions) in four editors, built around one shared implementation.
+definitions) in five editors, built around one shared implementation.

 | Directory | Contents |
 |---|---|
@@ -10,6 +10,7 @@ definitions) in four editors, built around one shared implementation.
 | `sublime/` | Sublime Text package.  Syntax file plus thin plugin wrappers that import the shared core directly (Sublime's plugin host is Python). |
 | `vim/` | Vim plugin.  Syntax/ftplugin files plus commands that run the shared core's CLI; with `+python3`, the core also runs in-process (`=` operator, live match highlighting). |
 | `vscode/` | Visual Studio Code extension.  TextMate grammar plus a dependency-free extension that spawns the language server and speaks LSP to it. |
+| `notepadpp/` | Notepad++ (Windows).  A User Defined Language for the highlighting, and two Run-menu commands that pass the current file through the shared core's CLI (delimiter check, reindent).  No plugin host, so nothing structural runs in-process. |

 ## The architecture

@@ -41,7 +42,8 @@ document/range formatting (reindentation), documentHighlight and
 definition (the matcher), and a `klammertext.alignTable` command.  The
 VS Code extension is its first client; any LSP client works — Neovim's
 built-in LSP, Emacs eglot, Sublime's LSP package — with a one-line
-configuration pointing at `python3 klammertext_ls.py`.
+configuration pointing at `python3 klammertext_ls.py` (on Windows
+`python klammertext_ls.py`).

 Syntax highlighting and cursor-latency features stay native in each editor
 (a tokenizer or a per-keystroke matcher cannot round-trip to Python), so
@@ -68,10 +70,12 @@ Two kinds of artifact cannot read it and restate parts of it by hand:
   defcustoms, checked byte-for-byte against the shared core by
   `tst/editor_test.sh`.
 2. **The static syntax files** — the literal-klammer set (`@code`) appears
-   in the Sublime `.sublime-syntax`, the Vim `syntax/klammertext.vim`, and
-   the VS Code `tmLanguage.json` grammar (and the Emacs defcustom).  When
-   you add a literal klammer, change them together; each file's header
-   carries the same SYNC note.
+   in the Sublime `.sublime-syntax`, the Vim `syntax/klammertext.vim`, the
+   VS Code `tmLanguage.json` grammar, and the Notepad++ `Klammertext.udl.xml`
+   (and the Emacs defcustom).  When you add a literal klammer, change them
+   together; each file's header carries the same SYNC note.  The UDL can
+   hold only names that are not prefixes of other klammer names (it has
+   no word boundary), so it carries `code` and not `c`.

 ## Testing

@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Klammertext.udl.xml - Notepad++ User Defined Language for Klammertext
+  (.kt documents and .k klammer definitions).  Highlighting only: Notepad++
+  has no Python plugin host and no built-in language-server client, so the
+  structural tools of the shared core (doc/edit/shared/klammertext_edit.py)
+  are reached through Run-menu commands instead; README.md has them.
+
+  What it colours, and how (a UDL is a fixed set of token classes, not a
+  grammar; the choices below are the closest fit):
+
+    @@@name, @@@       system commands      Keywords1, prefix match, orange
+    @@name,  @@        klammer definitions  Keywords2, prefix match, green
+    @name,   @         klammer applications Keywords3, prefix match, blue
+                       The groups are checked in order, longest run first,
+                       so @@name is not taken for an @ followed by a name.
+                       A named close (name@) is coloured only at its @.
+    ^X  ^UUUU^  ^'     escapes              Keywords4, prefix match, the
+                       default colour: consumed so the character after the
+                       caret is never read as a delimiter, shown as text
+                       (as the Emacs mode does).
+    # ...              removal to end of line   line comment, grey; only
+                       when the # is the first thing on its line
+                       (forcePureLC), because a UDL comment cannot tell
+                       "# comment" from the whitespace operators #- #+ #/,
+                       which would otherwise grey the rest of their line.
+    #[ ... ]#          removal of a region      block comment, grey, folds.
+    ## #- #+ #/        the other # forms        Operators2, marker red.
+    | :                bars and option marks    Operators1, marker red.
+    @code ... code@    verbatim interior        Delimiters1, muted, nothing
+                       inside it is coloured.  The other literal klammer,
+                       @c ... c@, is NOT here: a UDL delimiter has no word
+                       boundary, so "@c" would also open at @caption,
+                       @cond and every other c-klammer.
+
+  SYNC: the literal-klammer set's source of truth is LITERAL_KLAMMERS in
+  doc/edit/shared/klammertext_edit.py.  When a klammer is added there, add
+  "@NAME" / "NAME@" as a further delimiter pair here (pairs 2 to 8 are free:
+  items 03/05, 06/08, ... in the "Delimiters" list) - if its name is not a
+  prefix of other klammer names.
+
+  Colours are the palette's light-ground values (notes/klammertext_palette.md:
+  application 528599, definition 758B55, system 996743, markers 994040,
+  removed text 9A9A9A); colorStyle="1" keeps every background transparent, so
+  a dark Notepad++ theme keeps its own ground (the hues still read there).
+
+  Install: copy this file into %AppData%\Notepad++\userDefineLangs\ and
+  restart Notepad++ (or Language > User Defined Language > Define your
+  language... > Import...).  README.md has the details and the Run commands.
+-->
+<NotepadPlus>
+    <UserLang name="Klammertext" ext="kt k" udlVersion="2.1">
+        <Settings>
+            <Global caseIgnored="no" allowFoldOfComments="yes" foldCompact="no" forcePureLC="1" decimalSeparator="0" />
+            <Prefix Keywords1="yes" Keywords2="yes" Keywords3="yes" Keywords4="yes" Keywords5="no" Keywords6="no" Keywords7="no" Keywords8="no" />
+        </Settings>
+        <KeywordLists>
+            <Keywords name="Comments">00# 01 02 03#[ 04]#</Keywords>
+            <Keywords name="Numbers, prefix1"></Keywords>
+            <Keywords name="Numbers, prefix2"></Keywords>
+            <Keywords name="Numbers, extras1"></Keywords>
+            <Keywords name="Numbers, extras2"></Keywords>
+            <Keywords name="Numbers, suffix1"></Keywords>
+            <Keywords name="Numbers, suffix2"></Keywords>
+            <Keywords name="Numbers, range"></Keywords>
+            <Keywords name="Operators1">| :</Keywords>
+            <Keywords name="Operators2">## #- #+ #/</Keywords>
+            <Keywords name="Folders in code1, open"></Keywords>
+            <Keywords name="Folders in code1, middle"></Keywords>
+            <Keywords name="Folders in code1, close"></Keywords>
+            <Keywords name="Folders in code2, open"></Keywords>
+            <Keywords name="Folders in code2, middle"></Keywords>
+            <Keywords name="Folders in code2, close"></Keywords>
+            <Keywords name="Folders in comment, open">#[</Keywords>
+            <Keywords name="Folders in comment, middle"></Keywords>
+            <Keywords name="Folders in comment, close">]#</Keywords>
+            <Keywords name="Keywords1">@@@</Keywords>
+            <Keywords name="Keywords2">@@</Keywords>
+            <Keywords name="Keywords3">@</Keywords>
+            <Keywords name="Keywords4">^</Keywords>
+            <Keywords name="Keywords5"></Keywords>
+            <Keywords name="Keywords6"></Keywords>
+            <Keywords name="Keywords7"></Keywords>
+            <Keywords name="Keywords8"></Keywords>
+            <Keywords name="Delimiters">00@code 01 02code@ 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23</Keywords>
+        </KeywordLists>
+        <Styles>
+            <WordsStyle name="DEFAULT" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="COMMENTS" fgColor="9A9A9A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="LINE COMMENTS" fgColor="9A9A9A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="NUMBERS" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS1" fgColor="996743" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
+            <WordsStyle name="KEYWORDS2" fgColor="758B55" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
+            <WordsStyle name="KEYWORDS3" fgColor="528599" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
+            <WordsStyle name="KEYWORDS4" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS5" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS6" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS7" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS8" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="OPERATORS" fgColor="994040" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="FOLDER IN CODE1" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="FOLDER IN CODE2" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="FOLDER IN COMMENT" fgColor="994040" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS1" fgColor="5A5A5A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS2" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS3" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS4" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS5" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS6" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS7" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS8" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
+        </Styles>
+    </UserLang>
+</NotepadPlus>
@@ -0,0 +1,114 @@
+# 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`, which the Klammertext
+  installation already needs.
+
+## 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.
@@ -56,7 +56,10 @@ import sys
 # --- policy ----------------------------------------------------------------

 # Klammer names whose content is a literal argument (verbatim interior,
-# closed by a named NAME@ delimiter).
+# closed by a named NAME@ delimiter).  The static syntax artifacts restate
+# this set by hand (Emacs defcustom, .sublime-syntax, vim syntax, tmLanguage,
+# the Notepad++ UDL -- which can hold only "code"); doc/edit/README.md,
+# "Keeping things in sync".
 LITERAL_KLAMMERS = set(["code", "c"])

 # Klammers that contribute no indentation level (a @document's paragraphs
@@ -1037,6 +1040,13 @@ def _cli(argv):
    if len(argv) < 1:
        return usage()
    mode = argv[0]
+    # Klammertext writes LF on every system.  Python's text-mode stdout turns
+    # every "\n" into "\r\n" on Windows, and an editor -- or the test suite --
+    # comparing the result with an LF buffer then sees every line changed.
+    # stdin keeps universal newlines: a CRLF buffer arrives as "\n" lines,
+    # which is what the algorithms expect.
+    if hasattr(sys.stdout, 'reconfigure'):      # 3.7+; the floor is 3.8
+        sys.stdout.reconfigure(newline='\n')
    s = sys.stdin.read()

    if mode == 'indent':
@@ -203,8 +203,8 @@ 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
+`command: ["python3", "/path/to/klammertext_ls.py"]` (on Windows
+`"python"`) for the `text.klammertext` selector.  Everything in this package works the same
 with or without it.

 ## Troubleshooting
@@ -14,7 +14,8 @@ sync.
 ## Requirements

 - Vim 8+ (or Neovim) with `+eval` — any normal Vim; only `vim-tiny` lacks it.
- `python3` on `PATH` (Klammertext itself already requires Python).
+- `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`);
@@ -81,7 +82,7 @@ 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`.
+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)
@@ -92,7 +93,7 @@ toggle `#` line removal.
 | Variable | Meaning (default) |
 |---|---|
 | `g:klammertext_edit_py` | full path to `klammertext_edit.py` (auto-detected) |
-| `g:klammertext_python` | Python interpreter (`python3`) |
+| `g:klammertext_python` | Python interpreter (`python3`; on Windows `python`) |
 | `g:klammertext_no_mappings` | set to define no default mappings |

 ## Neovim and the language server
@@ -11,7 +11,8 @@
 " Configuration:
 "   g:klammertext_edit_py   full path to klammertext_edit.py (overrides the
 "                           search described below)
-"   g:klammertext_python    the Python interpreter (default "python3")
+"   g:klammertext_python    the Python interpreter (default "python3";
+"                           on Windows "python", the name python.org installs)

 " --- locating the shared core ---------------------------------------------
 " Search order: an explicit g:klammertext_edit_py; a vendored copy at this
@@ -37,7 +38,8 @@ function! s:EditScript() abort
 endfunction

 function! s:Python() abort
-  return exists('g:klammertext_python') ? g:klammertext_python : 'python3'
+  return exists('g:klammertext_python') ? g:klammertext_python
+        \ : (has('win32') ? 'python' : 'python3')
 endfunction

 " Run the core CLI over the whole buffer.  ARGS is the argument string
@@ -18,8 +18,9 @@ language's structure, everywhere.
 - VS Code 1.75 or later — a minimum, not a target: VS Code's monthly
  releases count 1.75, 1.76, … (1.75 is from January 2023), so any
  version from the last few years qualifies.
- `python3` on `PATH` (or set `klammertext.pythonPath`); Klammertext itself
-  already requires Python.
+- `python3` on `PATH` — on Windows `python`, the name python.org installs
+  (or set `klammertext.pythonPath`); Klammertext itself already requires
+  Python.
 - The language server, found automatically in this order:
  1. the `klammertext.serverPath` setting, if set;
  2. `klammertext_ls.py` vendored next to `extension.js` (the layout the
@@ -32,8 +33,9 @@ language's structure, everywhere.
 ## Install

 Package the extension as a `.vsix` and install it (the builder needs only
-bash and python3; the editing zip from the Klammertext website ships a
-prebuilt `klammertext.vsix`, so there the first step is already done):
+bash and Python — on Windows, run it in the MSYS2 shell the Klammertext
+build uses; the editing zip from the Klammertext website ships a prebuilt
+`klammertext.vsix`, so there the first step is already done):

    ./make_vsix.sh
    code --install-extension klammertext.vsix
@@ -129,7 +131,7 @@ Shortcuts** (`Ctrl+K Ctrl+S`), search "klammertext", and rebind.
 ## Settings

 A normal installation needs neither setting: the extension runs `python3`
-from `PATH` and finds the language server automatically (the copy vendored
+(on Windows `python`) from `PATH` and finds the language server automatically (the copy vendored
 next to `extension.js`, then `../shared/`, then
 `$KLAMMERTEXT_HOME/doc/edit/shared/`).  They exist for unusual setups.
 Set them in the Settings UI (`Ctrl+,`, search "klammertext") or in
@@ -138,10 +140,10 @@ reload the window after changing either.

 | Setting | Meaning (default) |
 |---|---|
-| `klammertext.pythonPath` | Python interpreter for the server (`python3`) |
+| `klammertext.pythonPath` | Python interpreter for the server (`python3`; on Windows `python`) |
 | `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |

-`pythonPath` matters when `python3` is not on the `PATH` VS Code sees — a
+`pythonPath` matters when the interpreter is not on the `PATH` VS Code sees — a
 VS Code launched from the desktop inherits a different environment than
 your shell — or when a specific interpreter is wanted.  `serverPath`
 matters only when the server file lives outside the search chain above.
@@ -165,7 +165,11 @@ function activate(context) {
            'diagnostics, formatting, matching and alignment need the server.');
        return;
    }
-    const python = vscode.workspace.getConfiguration('klammertext').get('pythonPath') || 'python3';
+    // The setting's declared default is empty so that this fallback is what
+    // decides: python3 everywhere but Windows, where python.org installs
+    // "python" only (the Klammertext commands there use the same name).
+    const python = vscode.workspace.getConfiguration('klammertext').get('pythonPath') ||
+        (process.platform === 'win32' ? 'python' : 'python3');
    client = new LspClient(python, [serverPath], log);
    client.proc.on('error', (err) => {
        vscode.window.showWarningMessage(
@@ -9,7 +9,7 @@
 #     code --install-extension klammertext.vsix
 #
 # A .vsix is a zip holding a two-file manifest plus the extension payload
-# under extension/.  This script builds it with bash + python3 only — no
+# under extension/.  This script builds it with bash + Python only — no
 # npm, no vsce — matching the extension's no-dependency design.  The shared
 # core and language server are vendored into the payload: from this folder
 # if present (the editing-zip layout), else from ../shared (the repository
@@ -18,6 +18,12 @@
 set -e
 cd "$(dirname "$0")"

+# The interpreter: $PYTHON if the environment names one (env/runtime.env
+# does), else python3, else python -- the only name python.org installs on
+# Windows, where this runs in the MSYS2 shell.
+PYTHON="${PYTHON:-$(command -v python3 || command -v python)}"
+[ -n "$PYTHON" ] || { echo "make_vsix.sh: no python3 or python on PATH" >&2; exit 1; }
+
 OUT="$PWD/klammertext.vsix"
 STAGE="$(mktemp -d)"
 trap 'rm -rf "$STAGE"' EXIT
@@ -36,7 +42,7 @@ for f in klammertext_edit.py klammertext_ls.py; do
    fi
 done

-VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
+VERSION=$("$PYTHON" -c "import json; print(json.load(open('package.json'))['version'])")

 cat > "$STAGE/[Content_Types].xml" <<'EOF'
 <?xml version="1.0" encoding="utf-8"?>
@@ -75,7 +81,7 @@ cat > "$STAGE/extension.vsixmanifest" <<EOF
 </PackageManifest>
 EOF

-python3 - "$STAGE" "$OUT" <<'EOF'
+"$PYTHON" - "$STAGE" "$OUT" <<'EOF'
 import os, sys, zipfile
 stage, out = sys.argv[1], sys.argv[2]
 with zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as z:
@@ -83,8 +83,8 @@
            "properties": {
                "klammertext.pythonPath": {
                    "type": "string",
-                    "default": "python3",
-                    "description": "Python interpreter used to run the Klammertext language server."
+                    "default": "",
+                    "description": "Python interpreter used to run the Klammertext language server.  Leave blank for python3 (on Windows: python)."
                },
                "klammertext.serverPath": {
                    "type": "string",
@@ -7,6 +7,8 @@ including `:haskell` and `:shell` commands that depend on locally installed
 software.

 For the container installation on Linux, see `linux_container_install.md`.
+On Windows, this page also applies unchanged inside the Windows Subsystem
+for Linux; `windows_wsl_install.md` says what is specific to WSL.


 ## Prerequisites
@@ -21,15 +23,19 @@ sudo apt-get install g++ make python3-dev
 The C++ compiler must support C++20. GCC 11 or later is required (Ubuntu 22.04
 and later include GCC 12+).

-The SKS `@image` klammer requires OpenImageIO Python bindings. These must match
-the Python version that ktext is built against (check with
-`python3.XX -c "import OpenImageIO"`). For example, if ktext links against
-Python 3.12:
+The SKS `@image` klammer requires the OpenImageIO Python bindings, for the
+same Python that ktext is built against (the system `python3`). Ubuntu
+packages them:

 ```bash
-pip3.12 install OpenImageIO
+sudo apt-get install python3-openimageio
+python3 -c "import OpenImageIO"
 ```

+(A `pip` install works too, but a fresh Ubuntu has no `pip` until
+`python3-pip` is installed, and since 24.04 it refuses to install into the
+system Python without `--break-system-packages`; the package avoids both.)
+
 Verify:

 ```bash
@@ -284,8 +290,8 @@ ktext -s '@eval 1 + 1 @' -d
 # Shell evaluation
 ktext -s '@eval :shell date @' -d

-# Show machine state (SKS is loaded by default)
-ktext -s '' -m
+# Show the machine's initial state: targets, argument types, the primitive klammers
+kdiag --machine

 # HTML and PDF output (uses the hello.kt from the Build section)
 ktext hello.kt -t html
@@ -13,6 +13,14 @@ The installation uses three things a Windows user installs once:
 building; **Python** from python.org, which Klammertext embeds; and **TeX
 Live**, for PDF output. Everyday use needs only PowerShell.

+This is one of three ways to have Klammertext on Windows. If you are at
+home in Linux, the Windows Subsystem for Linux gives you the Linux
+installation unchanged, with the Windows editors and browser alongside:
+`windows_wsl_install.md`. If you want no build at all, the prebuilt
+container images run on Windows through Docker Desktop, which that page
+also describes. This page is the native route: Windows programs, no
+Linux layer.
+

 ## Prerequisites

@@ -119,10 +127,11 @@ optimizing compiler may run out of memory and report `out of memory
 allocating`. If so, run `make -C com` without `-j`: slower, and it
 finishes.

-This builds the library, the Standard Klammer Set's components and the
-three commands into `bin\`, and copies the library and the compiler's
-runtime DLLs there too, so `bin\` is self-contained. The Python binding is
-built into `kpy\`. Verify:
+This builds the library (`klammertext.dll`), the Standard Klammer Set's
+components and the three commands (`ktext.exe`, `kdesc.exe`, `kdiag.exe`)
+into `bin\`, and copies the library and the compiler's runtime DLLs there
+too, so `bin\` is self-contained. The Python binding is built into `kpy\`.
+Verify:

 ```bash
 ktext -s '@eval 1 + 1 @' -d          # prints 2
@@ -221,21 +230,37 @@ ktext hello.kt -t pdf           # writes hello.pdf
 ## Using the commands from PowerShell

 Building needs the UCRT64 shell; using Klammertext does not. For everyday
-use from PowerShell, put three directories on the `Path` and set
+use from PowerShell, put two directories on the `Path` and set
 `KLAMMERTEXT_HOME`, once, as user environment variables (Settings ▸
-System ▸ About ▸ Advanced system settings ▸ Environment Variables, or with
-`setx`):
+System ▸ About ▸ Advanced system settings ▸ Environment Variables, or
+from PowerShell):

 ```powershell
-setx KLAMMERTEXT_HOME "C:\Users\<you>\klammertext"
-setx Path "$env:Path;C:\Users\<you>\klammertext\bin;C:\Users\<you>\external\texlive\2026\bin\windows"
+[Environment]::SetEnvironmentVariable("KLAMMERTEXT_HOME", "C:\Users\<you>\klammertext", "User")
+$p = [Environment]::GetEnvironmentVariable("Path", "User")
+[Environment]::SetEnvironmentVariable("Path", "$p;C:\Users\<you>\klammertext\bin;C:\Users\<you>\external\texlive\2026\bin\windows", "User")
 ```

-Python is already on the `Path` from its installer. Open a new PowerShell
+(Not `setx Path "$env:Path;…"`: `$env:Path` is the machine and user
+values merged, so that copies every machine entry into your user `Path`,
+and `setx` silently cuts a value over 1024 characters.) Python is already
+on the `Path` from its installer. Open a new PowerShell
 window and `ktext`, `kdesc` and `kdiag` work there directly. Paths
 Klammertext prints use forward slashes on every system; paths you type may
 use either.

+One PowerShell rule to know when you pass Klammertext text with `-s`: an
+apostrophe inside a single-quoted string ends the string, so `It's` must
+be written `It''s` (two apostrophes), or the whole text put in double
+quotes. The error you get otherwise mentions a "here-string header",
+because PowerShell reads the next `@'` as one; it is PowerShell's message,
+not Klammertext's.
+
+```powershell
+ktext -s '@i It''s a Pyrrhic victory! @' -d
+ktext -s "@i It's a Pyrrhic victory! @" -d
+```
+

 ## Verifying the installation

@@ -250,12 +275,12 @@ ktext hello.kt -t html                    # html
 ktext hello.kt -t pdf                     # pdf, requires TeX Live

 make -C $KLAMMERTEXT_HOME/tst test        # the engine's test suites
-make -C $KLAMMERTEXT_HOME/sks/tst test    # the Standard Klammer Set's suites (needs TeX Live)
 ```

 A few suite cases report `SKIP` on Windows for things the MSYS2 shell
 cannot provide, such as a real terminal for the colour tests or a
-symbolic link; that is expected.
+symbolic link; that is expected. (The Standard Klammer Set's own suites
+are part of the development repository, not of this distribution.)


 ## Updating
@@ -269,6 +294,56 @@ make -C com -j
 ```


+## Editor support
+
+Klammertext's editor support (`doc\edit\`, one shared implementation
+behind VS Code, Sublime Text, Vim and Emacs integrations) works on Windows
+with the Python already installed. Each editor's README in `doc\edit\`
+has the details; the Windows-specific steps are these.
+
+**Visual Studio Code.** Build the extension package in the UCRT64 shell,
+then install it from PowerShell (or from any window where `code` is on the
+`Path`):
+
+```bash
+cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh
+```
+
+```powershell
+code --install-extension C:\Users\<you>\klammertext\doc\edit\vscode\klammertext.vsix
+```
+
+Reload VS Code. The extension runs `python` from the `Path` and finds the
+language server inside the package; nothing needs configuring.
+
+**Sublime Text 4.** Copy the package and the shared core into Sublime's
+`Packages` directory (**Preferences ￫ Browse Packages…** opens it):
+
+```powershell
+$p = "$env:AppData\Sublime Text\Packages\Klammertext"
+New-Item -ItemType Directory -Force $p | Out-Null
+Copy-Item C:\Users\<you>\klammertext\doc\edit\sublime\* $p
+Copy-Item C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py $p
+```
+
+Sublime loads the package live.
+
+**Notepad++.** Highlighting comes from a User Defined Language file, the
+delimiter check and reindentation from two Run-menu commands
+(`doc\edit\notepadpp\README.md` has both):
+
+```powershell
+$d = "$env:AppData\Notepad++\userDefineLangs"
+New-Item -ItemType Directory -Force $d | Out-Null
+Copy-Item C:\Users\<you>\klammertext\doc\edit\notepadpp\Klammertext.udl.xml $d
+```
+
+Restart Notepad++; `.kt` and `.k` files open as Klammertext.
+
+**Vim.** As in `doc\edit\vim\README.md`; the plugin runs the shared core
+through `python` on Windows automatically.
+
+
 ## Troubleshooting

 **The command window closes at once, or "The code execution cannot proceed
@@ -282,7 +357,7 @@ runtime, which nearly every Windows machine already has but a freshly
 installed one may not. Install it from
 https://aka.ms/vs/17/release/vc_redist.x64.exe and try the import again.

-**"libklammertext.so was not found" or "libstdc++-6.dll was not found".**
+**"klammertext.dll was not found" or "libstdc++-6.dll was not found".**
 `bin\` is not on the `Path`, or the build did not finish: `make -C com -j`
 places the library and the runtime DLLs in `bin\` beside the commands.

@@ -0,0 +1,153 @@
+# Klammertext on Windows through the Windows Subsystem for Linux
+
+This page is for someone who works in Linux by habit and has a Windows
+machine to work on. The Windows Subsystem for Linux (WSL 2) runs a real
+Linux kernel and an ordinary Ubuntu inside Windows, and Klammertext's
+Linux installation applies there unchanged: the same compiler, the same
+Python, the same TeX Live, the same `runtime.env`. So this page is short.
+It gets you to an Ubuntu prompt, sends you to the Linux page, and then
+says what is specific to living in WSL: where files belong, how to look
+at the output from Windows, and how the Windows editors reach the Linux
+side. The steps were followed on a Windows 11 machine with WSL 2.7 and
+the Ubuntu it installs today, 26.04.
+
+There are two other ways to have Klammertext on Windows: as native
+Windows programs built from source (`windows_source_install.md`), and
+from the prebuilt container images, which this page covers at the end,
+since Docker runs inside WSL as it runs on Linux.
+
+
+## Getting Linux
+
+In a PowerShell window:
+
+```powershell
+wsl --install
+```
+
+This turns on the subsystem, installs the WSL layer and the current
+Ubuntu, and may ask you to restart Windows; do that before going on.
+Then open a terminal and type `wsl` (or start "Ubuntu" from the Start
+menu). The first start asks for a Linux username and a password; these
+are separate from your Windows account. Ubuntu may also ask whether to
+send platform metrics; you can say no. You are then at a bash prompt in
+your Linux home directory, and `wsl -l -v` in PowerShell shows Ubuntu as
+version 2.
+
+Two things worth knowing about the Ubuntu you now have: `sudo` works with
+the password you just chose, and the machine's Windows `Path` is appended
+to the Linux `PATH`, so Windows programs can be run from the Linux prompt
+by name (`explorer.exe`, `code`). That is convenient below and harmless
+otherwise; a Windows Python or TeX Live on the machine is not picked up
+by Linux, since Linux does not resolve `.exe` names.
+
+
+## Installing Klammertext
+
+Follow `linux_source_install.md` at the Ubuntu prompt, from its first
+line. Everything on it applies: the packages by `apt-get`, the clone, the
+line in `~/.bashrc` that sources `runtime.env`, the build, TeX Live by the
+bundled script, the verification. Nothing on that page is different
+inside WSL. On the machine this page was written on, the build took under
+a minute and TeX Live nine, and the engine's test suite passed as it does
+on Linux.
+
+Keep the clone and your documents in the Linux file system, under your
+Linux home, not under `/mnt/c`. The Windows drives are mounted there and
+work, but every file operation crosses between the two systems, and a
+build or a PDF run on `/mnt/c` is several times slower.
+
+
+## Seeing the output from Windows
+
+WSL has no browser or PDF viewer of its own, and it needs none. Windows
+sees the Linux file system as a network path, `\\wsl.localhost\Ubuntu\`,
+and Windows programs can open files there. From the Linux prompt, after
+`ktext hello.kt -t html` and `ktext hello.kt -t pdf`:
+
+```bash
+# at the Ubuntu prompt (type wsl in PowerShell to get there), not in PowerShell
+explorer.exe "$(wslpath -w hello/index.html)"
+explorer.exe "$(wslpath -w hello.pdf)"
+```
+
+`wslpath -w` turns a Linux path into the Windows form of the same file,
+and `explorer.exe` opens it with whatever Windows opens that kind of file
+with: your browser, your PDF viewer. The first time, Windows may ask
+which application to use. `explorer.exe .` opens the current Linux
+directory in Explorer, and from the Windows side the same files are in
+Explorer under "Linux" in the sidebar. (`explorer.exe` reports exit
+status 1 even when it succeeds; a script that needs a true status can use
+`powershell.exe -NoProfile -Command "Start-Process \"$(wslpath -w hello.pdf)\""`
+instead.)
+
+
+## Editors
+
+The Windows editors reach the Linux side, and the Linux editors are
+simply there.
+
+**Visual Studio Code**, the case this page was written for. Install VS
+Code on Windows and its "WSL" extension (Microsoft's
+`ms-vscode-remote.remote-wsl`). Then, at the Linux prompt, in the
+directory you want to work in:
+
+```bash
+code .
+```
+
+The first time, this installs VS Code's Linux-side server into your
+Linux home and opens a VS Code window on Windows connected to it. The
+Klammertext extension is installed on that Linux side, once, from the
+package built in the clone:
+
+```bash
+cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh && code --install-extension klammertext.vsix
+```
+
+Run from the Linux prompt, `code --install-extension` installs to the
+WSL side, where the extension then starts the Klammertext language
+server with the Linux `python3`; everything in `doc/edit/vscode/README.md`
+applies as on Linux. (Extensions installed on the Windows side of VS Code
+are a separate list and do not run in WSL windows.)
+
+**Emacs and Vim** are Linux programs: `sudo apt-get install emacs` or
+`vim`, then the Emacs and Vim packages under `doc/edit/` as on Linux.
+
+**Sublime Text and Notepad++** on Windows can open the Linux files
+through `\\wsl.localhost\Ubuntu\...` and highlight them with their
+Klammertext packages (`doc/edit/sublime/`, `doc/edit/notepadpp/`); their
+commands that run the shared core would run the Windows `python`, so for
+those two editors the native Windows installation is the better fit.
+
+
+## The container route
+
+If you would rather not build anything, the prebuilt Klammertext images
+run inside WSL exactly as `linux_container_install.md` describes, since
+the Ubuntu WSL installs today runs systemd and therefore Docker's
+service: follow that page at the Ubuntu prompt, from `apt-get install
+docker.io` on. That was done on the machine this page was written on:
+the image, 2.4 GB with its TeX Live, pulled in about a minute, and its
+`ktext` made the page's web page and PDF, owned by the Linux user. Docker
+Desktop for Windows is the other way to run the same images; its engine
+is WSL 2 as well, and it has its own licence terms for larger companies.
+
+
+## Troubleshooting
+
+**`wsl --install` says virtualization is not enabled.** WSL 2 needs the
+CPU's virtualization support turned on in the machine's firmware
+settings; the name varies (Intel VT-x, AMD-V, SVM). Turn it on and run
+the command again.
+
+**`code .` says the command is not found.** VS Code's `bin` directory is
+put on the Windows `Path` by its installer; open a new WSL terminal after
+installing VS Code, so the Linux `PATH` picks it up.
+
+**A build or a PDF run is slow.** The clone or the document is under
+`/mnt/c`. Move it under your Linux home.
+
+**The Ubuntu window asks for a username again.** The distribution was
+reset or reinstalled; the setup creates a fresh Linux home, and
+Klammertext must be installed again inside it.