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.

doc/install/linux_source_install.md

@@ -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

doc/install/windows_source_install.md

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

doc/install/windows_wsl_install.md

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