klammertext/doc/install/macos_container_install.md

# Running Klammertext on a Mac (Apple Silicon)

This guide gets Klammertext running on your Mac in a few minutes. You do
**not** need to install TeX Live, Python, or any programming tools —
everything, including the TeX Live system that makes PDFs, is packaged inside
a single downloadable image. You install Apple's `container` runtime once, and
then Klammertext works like a normal command.

This guide is for **Apple Silicon Macs (M1/M2/M3/M4/M5) running macOS 26 or
later**, which is what Apple's `container` runtime requires. (Support for older
Intel Macs can be provided separately if needed.)

## Step 1 — Install Apple's `container` runtime

`container` is Apple's own tool for running Linux container images natively on
Apple Silicon. It's free.

1. Go to <https://github.com/apple/container/releases> and download the latest
   installer package (the `.pkg` file). **Do not** use Homebrew — the Homebrew
   `container` formula is a different, unrelated tool.
2. Double-click the downloaded `.pkg` and follow the installer.
3. Open the **Terminal** app (Applications → Utilities → Terminal) and start the
   `container` background service (accept the recommended default if prompted):

   ```sh
   container system start
   ```

You only do this once. You can check the service any time with
`container system status`.

## Step 2 — Download Klammertext

In Terminal, paste this and press Return:

```sh
container image pull akopra/klammertext:latest
```

This downloads Klammertext and its built-in TeX Live. It's a few hundred
megabytes, so it takes a minute the first time. Because the image is multi-arch,
`container` fetches the native Apple Silicon (arm64) build. You won't need to do
this again unless you're updating.

## Step 3 — Add the Klammertext commands

This step makes `ktext` (and its helpers) available as ordinary commands.

1. In Terminal, create the wrapper file by pasting this whole block and
   pressing Return:

   ```sh
   cat > ~/klammertext.zsh <<'EOF'
   # Klammertext via Apple's `container` runtime (native arm64 image; no Rosetta).
   KLAMMERTEXT_IMAGE="${KLAMMERTEXT_IMAGE:-akopra/klammertext:latest}"
   _klammertext_run() {
     local cmd="$1"; shift
     container run --rm \
       -v "$PWD:/work" -w /work \
       "$KLAMMERTEXT_IMAGE" "$cmd" "$@"
   }
   ktext() { _klammertext_run ktext "$@"; }
   kdesc() { _klammertext_run kdesc "$@"; }
   kdiag() { _klammertext_run kdiag "$@"; }
   klammertext-update() {
     container image delete "$KLAMMERTEXT_IMAGE" 2>/dev/null
     container image pull "$KLAMMERTEXT_IMAGE"
   }
   EOF
   ```

2. Tell your shell to load it, by pasting this and pressing Return:

   ```sh
   echo 'source ~/klammertext.zsh' >> ~/.zshrc
   ```

3. **Close Terminal and open a new window** so the change takes effect.

You now have three commands — `ktext`, `kdesc`, `kdiag` — that run Klammertext
inside a container while reading and writing files in whatever folder you're
working in.

## Step 4 — Make your first document

In Terminal, go to a folder you want to work in (for example your Desktop) and
create a test file:

```sh
cd ~/Desktop
cat > hello.kt <<'EOF'
@document
:structure article
:title Hello
:text
@s1 Hello, Klammertext @

This document was produced on macOS with no TeX Live installed —
just Apple's `container` runtime and the Klammertext image.
@
EOF
```

Now produce a web page and a PDF from it:

```sh
ktext hello.kt -t html     # makes hello/index.html
ktext hello.kt -t pdf      # makes hello.pdf
```

Open the results:

```sh
open hello.pdf
open hello/index.html
```

That's it — you're running Klammertext.

## Good to know

- **Work inside one folder.** Klammertext can only see files in (or below) the
  folder you run the command from. Keep a document and the files it uses
  together, and run `ktext` from that folder.
- **Runs natively.** On Apple Silicon, `container` runs the native arm64 image
  with no Rosetta translation.
- **Fonts.** The default fonts (Crimson Pro, Open Sans, Inconsolata) are built
  in, so PDFs work with no internet connection. If you ask for a different font
  by name, Klammertext downloads it from Google Fonts the first time, which
  needs an internet connection.
- **Updating later.** When a new version is announced, run `klammertext-update`
  in Terminal.
- **If you also build Klammertext from source on this Mac.** Most people don't —
  the whole point of the container is that you don't need a source build. But if
  this machine *also* has a native source build on its `PATH` (so `which ktext`
  shows a path like `.../K/com/ktext`), the wrapper's `ktext` function would
  shadow that native command. To keep both, give the container wrappers their
  own names by using `ktextc` / `kdescc` / `kdiagc` (trailing `c` = container)
  in place of `ktext` / `kdesc` / `kdiag` in the Step 3 file. Then plain `ktext`
  still runs your source build and `ktextc` runs the container.
- **Quitting.** Klammertext only runs while you're using it; there's nothing
  left running afterward. If you want to stop the `container` service entirely,
  run `container system stop`; start it again with `container system start` next
  time.

## If something goes wrong

- **`command not found: ktext`** — you didn't open a new Terminal window after
  Step 3, or the `source` line didn't get added. Re-run the Step 3 commands and
  open a fresh Terminal.
- **`container: command not found`** — the `container` runtime isn't installed
  (Step 1), or the Terminal window predates the install (open a new one).
- **A command hangs or won't connect** — the `container` service isn't running.
  Run `container system start` (check with `container system status`), then try
  again.
- **A run aborted and now seems stuck** — `container run --rm` can leave the
  container behind after an error. Clear leftovers with:

  ```sh
  for id in $(container list -a -q); do container kill "$id"; container delete "$id"; done
  ```