Andy Kopra
61987c8b1f
mdpdf drives a headless Chromium, and a browser installed as a flatpak -- which is what the Pop!_Shop installs, and so the ordinary case on a Pop!_OS or System76 machine -- was unusable in two ways, the second of them silent. It was not found at all. A flatpak puts nothing on PATH and nothing in /opt, and its wrapper is named com.brave.Browser rather than brave-browser, so adding the export directory to PATH would not have helped either. The application ids are now looked for in the flatpak export directories, after every native browser, so a native one still wins where there is one. Found, it then rendered in the wrong fonts and reported success. The @font-face URLs pointed into the font store, which the sandbox cannot read, and a browser does not report a font it cannot fetch -- it substitutes. The PDF came out in a default serif and nothing said so. Granting the path would not have travelled either: sandbox filesystem permissions differ from one application to the next, so a scheme resting on a path works with one browser and fails with another on the same machine. So the document, its fonts and its images are now served to the browser over the loopback interface instead of being passed as file:// paths. Every sandbox shares the network namespace -- the DevTools connection already depends on it -- so this needs no filesystem permission from any sandbox, present or future. A --keep-html copy is still written with file:// URLs, so it works when nothing is serving it. A font that fails to load is now an error rather than a substitution: the page is asked whether each requested family arrived, and no PDF is written if one did not. A finished-looking document in the wrong typeface is the worst failure this program can have. Separately, a table-of-contents entry no longer carries a bullet. An entry is a section title, and a marker in front of it reads as a list of things rather than as a contents; ordinary bulleted lists are unaffected. (from dev 12929fdff53b)
10 KiB
Klammertext source installation on Linux (Ubuntu / Pop!_OS)
This document describes how to build and install Klammertext from source on a
Linux system — Ubuntu or Pop!_OS; the steps are identical — without using the
container. A source installation gives full access to all @eval modes,
including :haskell and :shell commands that depend on locally installed
software.
For the container installation on Linux, see linux_container_install.md.
Prerequisites
The following packages are required to build Klammertext:
sudo apt-get update
sudo apt-get install g++ make python3-dev
The C++ compiler must support C++20. GCC 11 or later is required (Ubuntu 22.04 and later include GCC 12+).
The SKS @image klammer requires OpenImageIO Python bindings. These must match
the Python version that ktext is built against (check with
python3.XX -c "import OpenImageIO"). For example, if ktext links against
Python 3.12:
pip3.12 install OpenImageIO
Verify:
g++ --version
Clone the repository
git clone https://git.andykopra.com/ack/klammertext.git
cd klammertext
Environment variables
Klammertext's runtime environment is provided by a single self-configuring
file. Source it from your shell profile (e.g., ~/.bashrc or ~/.zshrc):
source /path/to/klammertext/env/runtime.env
It self-locates KLAMMERTEXT_HOME from its own path, adds bin/ and
tst/ to PATH (plus the newest ~/external/texlive/<year>/bin/<arch> if a
TeX Live is installed there), sets LD_LIBRARY_PATH so libklammertext.so is
found, and sets the LSan suppressions. There is no per-host or per-OS variable
to set. For a TeX Live or library in a non-standard location, add it to an
optional, gitignored env/runtime.env.local (sourced at the end).
After editing your shell profile, reload it:
source ~/.bashrc
Configure the build
No build configuration is needed. The single env/makefile.env is
cross-platform: it reads KLAMMERTEXT_HOME from the environment (set by
runtime.env above), auto-detects the platform with uname, and auto-detects
Python with python3-config — no hardcoded version and no per-host file to
edit. Verify the Python development headers are present:
python3-config --includes # prints -I.../python3.XX for your Python
If python3-config is missing, install your distribution's python3-dev
(Debian/Ubuntu) or python3-devel (Fedora/RHEL) package.
Build
Build the shared library, the SKS components, and the three commands with a
single command: make -C com builds its prerequisites in mac/ and sks/
first, then the commands. The build is optimized (-O3) by default — the build
you want to install and run:
make -C com -j # lib/libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
(For a slower -O0 debug build with AddressSanitizer, intended for development,
prefix DEBUG=1: DEBUG=1 make -C com -j.)
Verify the build:
ktext -s '@eval 1 + 1 @' -d
This should print 2. For a quick document smoke test, create a small file and
render it to HTML:
cat > hello.kt <<'EOF'
@document
:structure article
:title Hello
:text
@s1 Hello, Klammertext @
This document was built from source.
@
EOF
ktext hello.kt -t html # writes hello/index.html
TeX Live (for PDF output)
The Standard Klammer Set uses XeLaTeX for the pdf target. Build a complete
Klammertext TeX Live tree with the bundled script, giving it a destination
directory under ~/external/texlive/<year> — the location runtime.env
auto-detects. The script needs perl, xz-utils, fontconfig, and either
wget or curl:
sudo apt-get install perl wget xz-utils fontconfig
bash $KLAMMERTEXT_HOME/doc/install/texlive_additional_packages.sh ~/external/texlive/2026
This installs scheme-small plus the additional packages the SKS needs and
rebuilds all formats, fetching the binaries for your architecture. It writes a
KLAMMERTEXT_BUILD_INFO.txt provenance file (mirror, release, package list,
date) into the tree.
Because the tree lives under ~/external/texlive/2026, runtime.env finds it
automatically — open a new shell (or re-source runtime.env) and xelatex
will be on PATH. No manual KLAMMERTEXT_TEXLIVE_BIN is needed.
If you would rather reuse a TeX Live you already have, point runtime.env at it
from the gitignored escape hatch instead, and install the SKS's extra packages
into it yourself (the package list is in doc/install/texlive_additional_packages.sh):
cat >> "$KLAMMERTEXT_HOME/env/runtime.env.local" <<'EOF'
export KLAMMERTEXT_TEXLIVE_BIN=/path/to/texlive/bin/x86_64-linux
export PATH="$KLAMMERTEXT_TEXLIVE_BIN:$PATH"
EOF
Verify and test (reusing the hello.kt from the Build section):
xelatex --version
ktext hello.kt -t pdf # writes hello.pdf
Optional: Haskell (for @eval :haskell)
The @eval :haskell mode requires runghc, which is part of the Haskell
toolchain. Alternatively, the akopra/klammertext:haskell container image
includes GHC (see linux_container_install.md).
The recommended way to install Haskell on Ubuntu is via ghcup:
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
Follow the prompts to install GHC, cabal, and related tools. After
installation, ensure the ghcup bin directory is in your PATH:
export PATH=$HOME/.ghcup/bin:$PATH
Verify:
runghc --version
Test in Klammertext:
ktext -s '@eval :haskell main = putStr "Hello from Haskell" @' -d
Optional: the mdpdf command (Markdown to PDF)
Klammertext ships a second, independent route in sks/tns/: mdpdf renders
a Markdown file to PDF through a headless browser, bypassing Klammertext
entirely. It is for a document that is not written in Klammertext — one you
have not converted yet, or one whose Markdown is not worth converting.
The command is a shell function that env/runtime.env defines, so if you
source that file (see Environment variables above) you already have it —
in shells started after the installation. In a shell that was already
running, source it again:
source $KLAMMERTEXT_HOME/env/runtime.env
type mdpdf # mdpdf is a shell function
Two things it needs that the distribution does not install:
# 1. The Markdown renderer, in a virtual environment of its own. PEP 668
# forbids installing it into the system Python, so this is not optional
# and not a system package.
python3 $KLAMMERTEXT_HOME/sks/tns/md_to_pdf.py --setup
# 2. A Chromium-based browser -- Brave, Chrome or Chromium -- which is the
# renderer. Any one of them will do; install whichever you prefer.
sudo apt install chromium-browser
A browser installed as a flatpak works too and is found without being
told: that is what the Pop!_Shop installs on Pop!_OS, and a flatpak puts
nothing on PATH, so the command looks for the application by name in the
flatpak export directories as well. The document is served to the browser
over the loopback interface rather than handed to it as a file path, so a
sandboxed browser needs no filesystem permission of any kind — including
none to reach the fonts, which is what silently cost a flatpak render its
typography before this was so.
Then:
mdpdf notes.md # writes notes.pdf beside it
mdpdf notes # the .md may be left off
It supplies the fonts, the size matching and the code wrapping, and completes
on *.md at the TAB key. Each default is a variable you may set in your
shell profile — MDPDF_SERIF, MDPDF_SANS, MDPDF_MONO, MDPDF_MATCH,
MDPDF_WRAP, and MDPDF_BROWSER for a browser installed somewhere the
command does not look. Any option of the underlying md_to_pdf.py may also
be given on the command line, where it overrides the default:
mdpdf notes.md --paper letter --margin 0.75
The stylesheet it applies is sks/tns/markdown.css; copy it, edit the copy,
and pass --css yourcopy.css to render to your own taste.
Directory layout after build
klammertext/
├── bin/ ktext, kdesc, kdiag executables (after build)
├── lib/ libklammertext.so shared library (after build)
├── mac/ Klammermachine C++ source
├── sks/ Standard Klammer Set (.k files and .so modules)
│ ├── document/ document.so
│ ├── kutil/ kutil.o
│ └── target/ html_util.o, latex_util.o
├── com/ command source (ktext, kdesc, kdiag) and Makefile
├── doc/ installation guides (doc/install) and editor support (doc/edit)
└── tst/ test suites
Verifying the installation
Run the following commands to verify that everything works:
# Basic evaluation (Python)
ktext -s '@eval 1 + 1 @' -d
# Shell evaluation
ktext -s '@eval :shell date @' -d
# Show machine state (SKS is loaded by default)
ktext -s '' -m
# HTML and PDF output (uses the hello.kt from the Build section)
ktext hello.kt -t html
ktext hello.kt -t pdf # requires TeX Live
# Haskell evaluation (requires ghcup)
ktext -s '@eval :haskell main = putStr "42" @' -d
# Run unit tests
make -C $KLAMMERTEXT_HOME/tst test
Updating
To update an existing source installation to the latest version:
cd $KLAMMERTEXT_HOME
git pull
make -C com -j # rebuild library, SKS components, and commands (optimized)
The TeX Live tree only needs rebuilding if the SKS's package requirements changed (rare); when they do, re-run the script from the TeX Live section above.
Troubleshooting
"libklammertext.so: cannot open shared object file"
Ensure LD_LIBRARY_PATH includes $KLAMMERTEXT_HOME/lib:
export LD_LIBRARY_PATH=$KLAMMERTEXT_HOME/lib:$LD_LIBRARY_PATH
"KLAMMERTEXT_HOME is not set" Set the environment variable as described in the Environment variables section above.
"python3.XX/Python.h: No such file or directory" Install the Python development headers:
sudo apt-get install python3-dev
"xelatex: command not found" (when using -t pdf)
Install TeX Live and ensure its bin directory is in PATH.
"@eval :haskell requires runghc" Install Haskell via ghcup as described in the Optional: Haskell section.