ack/klammertext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Literal @c, @source_listing with :marker, and a large-directory speedup

Browse Source 
Three changes.

@c now takes its content literally, like @code -- it is the inline form
and @code the block form of the same thing.  The named close "c@" is
required, and characters that are special in a target no longer break
the file: @c a_b c@ renders correctly everywhere.  The Markdown
converter stops quoting inline code, since nothing needs protecting.

@source_file is renamed @source_listing.  Code read from a file is its
own klammer; @code is only for a block written inline (its never-
implemented :filename and :pattern options are removed).  The new
:marker P option lists the region between two lines that are exactly
//P, so the source file declares its own extractable regions.  A marker
missing or not appearing exactly twice is an error, never a fallback.

Rendering a document that sits in a large directory was paying a
recursive walk of that directory's whole tree on every @eval -- 27
seconds for a document that renders in a third of one.  The walk is now
a non-recursive look decided once per directory.

Assembled from dev commit 071b1b183de4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Andy Kopra
2026-08-16 16:58:50 +02:00
parent 8b38a34841
commit bd39d9a369
8 changed files with 284 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/klammertext_for_llm.md
View File

@@ -92,7 +92,7 @@ klammer's name immediately before it: `@i text i@.
```
@i just text i@ ← unnecessary; @i just text @ is better
@s1 A @c literal c@ heading s1@ ← name it: the body contains a klammer call
@s1 A @c fragment c@ heading s1@ ← name it: the body contains a klammer call
```
**Arguments.**
@@ -110,17 +110,42 @@ klammer's name immediately before it: `@i text i@.
**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 (`@c`, `@code`). Their
content is not scanned for `@`, `|`, `#`, or `^`, so the machine cannot find the
end by counting — **these must be closed with the named form**:
**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**:
```
@c ImfStandardAttributes.h c@
@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
@@ -137,7 +162,7 @@ code@
@s1 Principles s1@
Ordinary paragraph text. A blank line starts a new paragraph.
Use @i emphasis i@ and @b bold @ inline, and @c literal_text c@ for code.
Use @i emphasis i@ and @b bold @ inline, and @c code_fragment c@ for code.
@link https://openexr.com/ :text the OpenEXR site link@
@@ -172,9 +197,9 @@ Confirm parameters with `kdesc -k <name>` — this list is names and intent only
| | |
|---|---|
| inline | `@i` italic, `@b` bold, `@t` typewriter, `@u` underline, `@c` inline literal, `@sup`, `@sub` |
| 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`, `@quote`, `@note`, `@indent`, `@block`, `@center`, `@right`, `@columns` |
| 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` |