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):

   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:

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:

   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:

   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:

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:

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

Open the results:

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:

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