klammertext/doc/klammertext_for_llm.md

Klammertext — reference for an LLM assistant

For a language model helping someone author Klammertext documents. Dense and example-led on purpose: it is not a tutorial, and it motivates nothing. A person wanting to learn Klammertext should read the other documents in doc/.

Read §1 and §2 before writing any Klammertext. §2 exists because a model that has not seen this language will pattern-match it to LaTeX, Markdown, or Lisp and produce confidently wrong syntax.

The klammers named here are the Standard Klammer Set, which is what loads by default. A klammer set is user-extensible, so the authority for what exists in any particular setup is kdesc, not this file — see §1.

---

1. Do not guess — the machine will tell you

Klammertext is introspectable. kdesc prints the live state of the machine's data structures in digested form: what klammers exist, what arguments each takes, what the argument types accept, what targets exist. Query it instead of inferring from examples.

ask	command
every klammer, with parameters and description	kdesc -k
klammers whose name or description mentions X	kdesc -k X
the output targets	kdesc -t
argument types and what each accepts	kdesc --argtypes
shared option groups and who uses them	kdesc --optionsets
which targets each klammer can render to	kdesc --coverage
what a user's own file defines	kdesc -i FILE -k
the usage of any command	run it with no arguments

kdesc -k <name> before using an unfamiliar klammer costs one command and replaces a guess. The parameter list it prints is authoritative; this file is not.

Check a document without rendering it:

kdiag --process --check doc.kt

reports every klammer application whose name, argument count, option names, or target coverage is wrong — including inside branches this render will not take. It applies nothing, so it is safe and fast. Use it before claiming a document is correct.

Inspect how text is being parsed: kdiag --type '<text>' shows the tokens ("katoms") and their types. This settles arguments about what a piece of syntax actually means.

---

2. What you will get wrong if you assume

assumption	reality
It is a macro language like TeX	No catcodes. Token structure is fixed when a file is read and cannot be changed by anything later. This is why static checking works.
\command{arg}	@name arg @ — an @ opens, and a closing delimiter is required.
Arguments are {a}{b}	Positional arguments are separated by `
Options are [key=value]	:name value, anywhere in the argument list — @link URL :text Click @.
% starts a comment	# removes the rest of the line. ## removes the rest of the file. #[ … ]# removes a block.
Whitespace is insignificant	It is content, and it is preserved. Blank lines separate paragraphs.
\\ escapes	^ quotes: ^@ ^| ^# ^^ ^: produce those characters literally.
Text is nested in braces	Text lives between the opening and closing delimiter with no wrapper.
The document body is the first argument	For @document the body goes in the :text option (or :files). A positional body is an error.

---

3. Lexical core

Three prefix tiers, distinguished by how many @:

written	tier	meaning
@name	application	use a klammer
@@name	definition	define a klammer
@@@name	system	modify the machine (targets, argument types, state, klammersets)

Closing a klammer. The close is @ for the application tier, @@ for definitions, @@@ for system commands. A close may be named by putting the klammer's name immediately before it: `@i text i@.

When to name the close. Use a bare @ by default. Use the named form name@ when the klammer's body contains other klammer calls. The reason is diagnostic, not stylistic: if delimiters are unbalanced, a named close lets the machine say exactly which klammer was left open. With bare closes everywhere it can only report that the count did not work out. Do not name closes on short, klammer-free bodies — it is noise.

@i just text i@                      ← unnecessary; @i just text @ is better
@s1 A @c fragment c@ heading s1@     ← name it: the body contains a klammer call

Arguments.

@name positional1 | positional2 :option value :flag @

• | separates positional arguments.
• :name value is an optional argument; it may appear anywhere in the list.
• :name written alone takes the argument type's "alone" value — for a boolean that is true, so :number means :number true.
• An optional argument that is not written takes its default.

Abbreviated form. @name-arg1-arg2 is @name arg1 | arg2 @, valid only while every argument is letters and digits: @i-italic, @sup-2-3, @date@.

Literal klammers take their content uninterpreted. It is not scanned for @, |, #, or ^, so the machine cannot find the end by counting and the named close is required:

@code
  int x = a[0];   // # and @ are safe in here
code@

@c a | b c@      ← inline: same rule, and the close must be "c@"

@c and @code are the in-line and block forms of the same thing, and both are literal: nothing inside either is interpreted, so #, @, |, ^ and * all pass through as written and none of them needs quoting.

Code that lives in a file is @source_listing, never @code — @code is only for a block written out inline, and has no filename argument:

@source_listing src/derivations.cpp @              ← the whole file
@source_listing src/derivations.cpp :marker fromRdd55 @   ← one region of it

:marker P lists what lies between two lines that are exactly //P, each beginning in the first column. The source file thus declares its own extractable regions and the document asks for one by name, so editing the code cannot silently change what the document shows. A marker that is missing, or that does not appear exactly twice, is an error — never a silent fallback to the whole file.

kdesc -k <name> is how you tell: a parameter shown as text.literal is a literal parameter. Do not infer it from a klammer's purpose — check.

---

4. A complete document

@document
:title Normalizing to OpenEXR Standard Attributes
:subtitle Predictability and provenance
:author Joseph Goldstone
:date @date@
:point_size 12
:text

@s1 Principles s1@

Ordinary paragraph text. A blank line starts a new paragraph.
Use @i emphasis i@ and @b bold @ inline, and @c code_fragment c@ for code.

@link https://openexr.com/ :text the OpenEXR site link@

@ul
  first item
| second item
| third item
ul@

# A comment: removed, and never reaches the output.

@image figure_name :width .95w :caption A caption @

@

Render it:

ktext doc.kt -t pdf         # also: -t html, -t tex, -t txt
ktext doc.kt -t html        # writes a DIRECTORY doc/ containing index.html
ktext -s '@i-x' -t html -d  # -d displays instead of writing; -s takes a string

Output goes next to the input file unless -o says otherwise.

---

5. Klammers most used when authoring

Confirm parameters with kdesc -k <name> — this list is names and intent only.

inline	@i italic, @b bold, @t typewriter, @u underline, @c inline code (literal; close with c@), @sup, @sub
structure	@s1…@s7 numbered headings, @h1…@h7 unnumbered, @part, @preface, @par
blocks	@code (a listing written inline), @source_listing (a listing read from a file), @quote, @note, @indent, @block, @center, @right, @columns
lists	@ul unordered, @ol ordered, @define term/definition — items separated by |
tables	@table — cells by |, rows by ||; @tbl, @rowcolor
figures	@image, @image_grid, @fig, @reference
other	@link, @date, @datetime, @color, @font, @newpage, @vspace, @email

Bar depth is the dimension: one | separates items, two || separates rows.

---

6. Defining a klammer (only if asked)

@@name.k arg1 | arg2 :opt default : Description of what it does @@
@@name.html :: <span>*arg1*</span> @@
@@name.tex  :: \textbf{*arg1*} @@

• .k declares the interface and documents it; per-target definitions inherit the parameter list with ::.
• *arg* substitutes an argument into the body.
• A definition with no target suffix applies to every target.
• Separators: : create, :: create inheriting parameters, ::: override an existing definition, :::: define a default that a later : may replace.

---

7. Behaviour worth knowing before you debug something

• @cond is strict about truth. True: true, True, 1. False: false, False, 0, and empty. Anything else is an error, not "probably false".
• @cond evaluates only the branch it selects. The branch not taken is not read, not evaluated, not expanded — a @read of a missing file in the unused branch is harmless.
• A state variable reaches a @cond predicate. The document behaves like a function body whose arguments are its @@@state variables.
• @eval :shell and :haskell: the command's standard output becomes document text; its standard error does not (it appears under -v 1); a nonzero exit is an error. Append || true if a nonzero exit is expected.
• A definition inside a @cond branch does not register — in either branch. Define outside and select between applications.

---

8. Diagnostics

• -v 1 reports every decision the command made that the user could not have read off their own input: which klammerset was loaded and from where, which file a font or a :files name resolved to, how the output path was built. Higher levels are an implementation trace.
• Logging and errors go to standard error; the rendered document goes to standard output, so ktext doc.kt -d | … is safe.
• An error stops the run and names a file, line, and character. There is no warn-and-continue except in two documented cases.
• A bare ktext, kdesc, or kdiag prints its usage and exits successfully.

When something is wrong: run kdiag --process --check doc.kt first — it finds name, arity, option and coverage faults without rendering. Then kdesc -k <klammer> to check the parameter list against what was written. Then kdiag --type '<fragment>' if the question is how something is being parsed.