Initial commit: Klammertext source distribution
Curated source subset assembled by klammertext-dev's doc/make_dist.sh: the Klammermachine (mac), the Standard Klammer Set (sks), the commands (com), editor plugins and install guides (doc), a test subset (tst), and lib/bin placeholders. Builds with 'make -C com'. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
161
doc/install/macos_container_install.md
Normal file
161
doc/install/macos_container_install.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user