149 lines
4.7 KiB
Markdown
149 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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, 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 machine, 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
|
|
|
|
- **`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):
|
|
|
|
```bash
|
|
docker rmi akopra/klammertext:latest
|
|
docker system prune # optional: remove all unused Docker data
|
|
```
|