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: the first start sets up the service's kernel. After a restart the service is down again, and the wrapper you install in Step 3 starts it for you the next time you run a Klammertext command. 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, and others) are built in, so PDFs work with no internet connection. Font resolution is entirely offline: asking for a font that isn't installed lists the available fonts, and additional fonts are installed from font files you already have with kdesc --typeface install <folder> (kdesc --typeface help explains).
• 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; the wrapper starts it again the next time you run a Klammertext command.

Editor support (Emacs, Sublime Text)

Editing Klammertext is nicer with editor support: syntax highlighting, delimiter matching, indentation, table alignment, and diagnostics for Emacs, Sublime Text, Vim, and Visual Studio Code. It is not inside the container image — it belongs on your Mac, next to your editor. Download it from either place:

• https://andykopra.com/Klammertext_editing.zip — unpacks to emacs/, sublime/, vim/, and vscode/ folders, each self-contained
• the Klammertext source repository, https://git.andykopra.com/ack/klammertext, directory doc/edit/

Each package's README explains its installation.

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

• the container service did not start — the wrapper starts the container service when it is down, and this time it could not. Run container system start yourself to see the service's own message (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