klammertext/doc/install/windows_wsl_install.md

# Klammertext on Windows through the Windows Subsystem for Linux

This is how Klammertext is installed on Windows. 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.

The commands are Linux programs, run from the Ubuntu prompt; there is no
native Windows build. The other way to have Klammertext on Windows is 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 open the Linux files through
`\\wsl.localhost\Ubuntu\...`, with their Klammertext packages
(`doc/edit/sublime/`, `doc/edit/notepadpp/`) installed on the Windows
side. The packages are self-contained: they highlight, and their commands
-- matching delimiters, reindentation, table alignment, the delimiter
check -- are Python programs that never run Klammertext itself, so the
Linux side is not involved. Sublime Text runs them in its own
interpreter. Notepad++'s Run commands, and the optional language server
for Sublime Text, start `python`, which means a Python for Windows from
python.org on the `Path`.


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