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