klammertext/doc/install/linux_container_install.md

Running Klammertext on Linux with Docker

This guide runs Klammertext on a Linux system (Ubuntu or Pop!_OS — the steps are identical) using the prebuilt Docker container. 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 Docker once, then Klammertext works like a normal command.

The published image is multi-arch, so Docker pulls the build matching your CPU (amd64 on Intel/AMD, arm64 on ARM machines) automatically.

For a source build instead (full @eval access, no Docker), see linux_source_install.md.

Step 1 — Install Docker

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect (so you can run docker without sudo). You only do this once.

Step 2 — Download Klammertext

docker pull akopra/klammertext:latest

This downloads Klammertext and its built-in TeX Live (a few hundred megabytes). You won't need to do it again unless you're updating.

Step 3 — Add the Klammertext commands

Add these aliases to ~/.bashrc (or ~/.zshrc) so ktext, kdesc, and kdiag work as ordinary commands that read and write files in whatever folder you run them from:

alias ktext='docker run --rm -u $(id -u):$(id -g) -v "$PWD:/work" -w /work akopra/klammertext ktext'
alias kdesc='docker run --rm -v "$PWD:/work" -w /work akopra/klammertext kdesc'
alias kdiag='docker run --rm -v "$PWD:/work" -w /work akopra/klammertext kdiag'

The -u $(id -u):$(id -g) on ktext makes output files owned by you rather than root. kdesc and kdiag only read files, so they don't need it. The -v "$PWD:/work" mounts your current directory into the container as /work, which is required for the commands to see your files.

Reload your shell (open a new terminal, or source ~/.bashrc).

Step 4 — Make your first document

In a folder you want to work in, create a test file:

cat > hello.kt <<'EOF'
@document
:structure article
:title Hello
:text
@s1 Hello, Klammertext @

This document was produced with no TeX Live installed — just Docker and the
Klammertext image.
@
EOF

Produce a web page and a PDF:

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

That's it — you're running Klammertext.

Updating

To update to the latest published image:

docker pull akopra/klammertext:latest

Haskell support (@eval :haskell)

The standard image does not include Haskell. For @eval :haskell, pull the Haskell image and use it in place of the standard one:

docker pull akopra/klammertext:haskell
alias ktext='docker run --rm -u $(id -u):$(id -g) -v "$PWD:/work" -w /work akopra/klammertext:haskell ktext'

Test:

ktext -s '@eval :haskell main = putStrLn "hello" @' -d

Alternatively, a source install gives all @eval modes without a separate image (see linux_source_install.md).

Klammer set loading

The Standard Klammer Set is loaded by default. To load a different klammer set, pass -k PATH (the klammer set's .k file). To run with only the three primitive klammers (@read, @eval, @cond), use -k none.

Editor support (Emacs, Sublime Text)

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

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

Each package's README explains its installation.

If something goes wrong

• Cannot connect to the Docker daemon — the Docker service isn't running: sudo systemctl start docker, then retry.
• permission denied running docker — your user isn't in the docker group yet: sudo usermod -aG docker $USER, then log out and back in.
• No such file or directory for your input — the file must be in the directory you run the command from (that's what gets mounted). cd into the folder with your .kt files first.
• Output files owned by root — add -u $(id -u):$(id -g) to the ktext command/alias (as shown in Step 3).

Freeing disk space

To remove the image (you can re-pull it later):

docker rmi akopra/klammertext:latest
docker system prune          # optional: remove all unused Docker data