2026-07-18 18:48:23 +02:00
|
|
|
# Klammertext
|
|
|
|
|
|
|
|
|
|
Klammertext is a markup language that produces multiple output formats —
|
|
|
|
|
HTML, LaTeX/PDF, and plain text — from a single source description. Its core
|
|
|
|
|
engine, the Klammermachine, is written in C++; the Standard Klammer Set (SKS)
|
|
|
|
|
adds a default library of formatting and document-structuring operators on top.
|
|
|
|
|
|
|
|
|
|
## Installing
|
|
|
|
|
|
|
|
|
|
Installation guides are in [`doc/install/`](doc/install/):
|
|
|
|
|
|
|
|
|
|
- Linux, from source — `doc/install/linux_source_install.md`
|
|
|
|
|
- macOS, from source — `doc/install/macos_source_install.md`
|
|
|
|
|
- Linux, container — `doc/install/linux_container_install.md`
|
|
|
|
|
- macOS, container — `doc/install/macos_container_install.md`
|
|
|
|
|
|
|
|
|
|
## Building from source
|
|
|
|
|
|
|
|
|
|
With a C++20 compiler and `KLAMMERTEXT_HOME` set to this directory:
|
|
|
|
|
|
|
|
|
|
make -C com
|
|
|
|
|
|
|
|
|
|
This builds the Klammermachine library (into `lib/`), the SKS components, and
|
|
|
|
|
the three commands — `ktext`, `kdesc`, `kdiag` (into `bin/`). See the
|
|
|
|
|
source-install guide for prerequisites (TeX Live for PDF output, Python, and so
|
|
|
|
|
on).
|
|
|
|
|
|
A reference for an LLM assistant: doc/klammertext_for_llm.md
If you use a language model to help write Klammertext, give it this file. It is
a dense reference written for a model rather than a person -- not a tutorial,
and it motivates nothing.
Two things make it different from the other documents here.
It tells the model NOT TO GUESS. Its first section maps questions to commands,
because "kdesc" prints the live state of the machine's data structures: what
klammers exist, what arguments each takes, what the argument types accept. The
file says outright that the parameter list kdesc prints is authoritative and
that the file is not, so a model checks rather than infers. "kdiag --process
--check doc.kt" verifies a document without rendering it, and "kdiag --type"
settles how a fragment is being parsed.
Its second section is a table of WRONG ASSUMPTIONS. A model that has not seen
Klammertext pattern-matches it to LaTeX, Markdown or Lisp and produces
confidently wrong syntax, so each row names the likely wrong guess and corrects
it -- braces against the bar separator, bracketed options against ":name value",
"%" against "#", backslash escapes against "^", and @document's body belonging
in its ":text" option rather than in a positional argument.
The rest is the syntax proper: the three "@" tiers, argument forms, a complete
worked document, the klammers most used when authoring, how to define one, and
the behaviour that otherwise costs a debugging session.
The README points at it.
Assembled from dev commit 6c2ff7b8fce3.
2026-08-16 13:19:34 +02:00
|
|
|
## Working with an AI assistant
|
|
|
|
|
|
|
|
|
|
If you use a language model to help write Klammertext, give it
|
|
|
|
|
[`doc/klammertext_for_llm.md`](doc/klammertext_for_llm.md). It is a dense
|
|
|
|
|
reference written for a model rather than a person: the syntax, the things a
|
|
|
|
|
model is most likely to assume wrongly about it (Klammertext is not LaTeX,
|
|
|
|
|
Markdown, or Lisp, and reads oddly if you expect any of them), and how to ask
|
|
|
|
|
the `kdesc` and `kdiag` commands for the current state of the machine instead
|
|
|
|
|
of guessing.
|
|
|
|
|
|
2026-07-18 18:48:23 +02:00
|
|
|
## Editor support
|
|
|
|
|
|
Editor support generalized: shared core, language server, Vim and VS Code (from dev eb5baf9cbe59)
doc/edit/ now holds a shared Python implementation of the language's
structural layer (klammertext_edit.py) and a dependency-free language
server (klammertext_ls.py), with integrations for Emacs, Sublime Text,
Vim, and Visual Studio Code. The editor test suite in tst/ covers the
core's API and CLI, the language server protocol, the VS Code
extension, headless Vim, and Emacs byte-equality.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-27 15:01:49 +02:00
|
|
|
Editing support for Emacs, Sublime Text, Vim, and Visual Studio Code —
|
|
|
|
|
syntax highlighting, delimiter matching, structural reindentation, table
|
|
|
|
|
alignment, diagnostics — is in [`doc/edit/`](doc/edit/), together with the
|
|
|
|
|
shared implementation and the Klammertext language server they build on.
|
2026-07-18 18:48:23 +02:00
|
|
|
|
2026-07-26 01:07:52 +02:00
|
|
|
## Provenance
|
|
|
|
|
|
|
|
|
|
This repository is a curated snapshot of Klammertext's private development
|
|
|
|
|
tree, assembled by a manifest-driven script. Its history is a series of
|
|
|
|
|
release snapshots, not a mirror of the development history, and files here
|
|
|
|
|
are regenerated on each release — patches cannot be merged directly.
|
|
|
|
|
Report problems (or send patches) to the author; accepted changes are
|
|
|
|
|
applied to the development tree and appear in a following snapshot.
|
|
|
|
|
|
2026-08-18 00:28:09 +02:00
|
|
|
This snapshot was assembled from development commit `f34e66a4dbfb`.
|
2026-07-26 01:07:52 +02:00
|
|
|
|
2026-07-18 18:48:23 +02:00
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
See [`LICENSE.md`](LICENSE.md).
|