---
title "Literate Programming with CentrMark"
author "amdphreak"
date 2026-03-28
tags "literate-programming", "specification", "evolution"
---

= Literate Programming with CentrMark

Literate programming is the discipline of creating software documents where the primary narrative structure is human-oriented, not machine-oriented. Historically, systems like CWEB and noweb used "Tangle" and "Weave" processes to extract code and generate documentation.

CentrMark evolves this by implementing **Synchronous Literate Programming (SLP)** via its flexible Directive system and AST-first design.

== 1. The Core Directives

In CentrMark, code is treated as a component of the document's evolution. Unlike markdown's static fenced code blocks, CentrMark uses **Block Directives** to manage code extraction and transformation.

=== 1.1 Tangle Directive
The `::: tangle` directive specifies a source file to be generated or updated.

::: tangle [file="hello.c" lang="c"]
```c
#include <stdio.h>

int main() {
  printf("Hello, World!\n");
  return 0;
}
```
:::

=== 1.2 Fragment Directive
Define named code snippets that can be referenced or combined.

::: fragment [name="main-loop"]
```c
while (app_is_running()) {
  update_state();
  render();
}
```
:::

== 2. Synchronous Literate Programming (SLP)

The "Architectural Gap" in traditional LP is the disconnect between document and execution. CentrMark solves this through **Structural Synchronization**.

0. **Unified AST Database**: Every `.cmk` file is parsed into a rich AST where narrative and code blocks are sibling nodes.
0. **Timeline Evolution**: Code blocks can be marked with `version` or `evolution` properties.
0. **Replay Scrubber**: The `dev-centr` GUI can traverse these versions, allowing users to "scrub" through the construction of the app.

::: code-evolution [id="setup" version="1.0"]
```javascript
const app = new App();
app.start();
```
+
((
Wait, version 1.1 needs more complex initialization for the GPU.
))
+
::: code-evolution [id="setup" action="replace" version="1.1"]
```javascript
const app = new App({ gpu: true });
app.init().then(() => app.start());
```
:::

== 3. Recommendations for CommonMark

For developers who prefer standard Markdown, we recommend:

* **Quarto**: The industry standard for data science and complex multi-file literate documents.
* **nbdev**: A Python-centric system that turns Jupyter notebooks into formal libraries.
* **Entangled**: A language-agnostic "Syncer" that monitors Markdown and source code for bi-directional changes.

((
The goal of CentrMark is to make the "Tangle" process invisible. When you save your document, the code is already there. Better yet, when you change the code in your IDE, the document is updated.
))