diff --git a/examples/foreign-writeback/index.mq.md b/examples/foreign-writeback/index.mq.md deleted file mode 100644 index e37441c..0000000 --- a/examples/foreign-writeback/index.mq.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Foreign result writeback -description: Execute a foreign code fence and persist the result into this .mq.md -import foreign:lib/foreign.mq.md -import writeback:lib/writeback.mq.md ---- - -# main - -This is a runnable example, not a screenshot. Run it with: - -```text -marqdo run examples/foreign-writeback/index.mq.md -``` - -The foreign fence below is a normal Marqdo code value. `foreign.run` executes it; -`writeback.record` writes the result into a keyed output slot immediately below -the call. Re-running replaces only the `total` slot. - -`合计代码` = -```python -print(950) -``` - -**结果 = > foreign.run code=`合计代码`** - -**> writeback.record value=`结果` key="total"** - - -The keyed slot below is generated by the run: - -查看源码,确认 `total` 槽位就在这次 writeback 调用下方。 diff --git a/public/features/21-persistence.mq.md b/public/features/21-persistence.mq.md index dd022e6..e0071e2 100644 --- a/public/features/21-persistence.mq.md +++ b/public/features/21-persistence.mq.md @@ -1,6 +1,8 @@ --- title: Persisting foreign execution results description: Static snapshots and writeback — how foreign results survive after the process exits +import foreign:lib/foreign.mq.md +import writeback:lib/writeback.mq.md --- # main @@ -9,7 +11,7 @@ Foreign code has two useful lives: as a published snapshot, and as a living docu --- -## Static snapshot: publish the result +Static snapshot: publish the result. `marqdo view output` executes the document's cells and embeds their real output in the generated HTML. The `.mq.md` source is not modified. This is the default choice for user documentation, reviews and stable links: a reader sees the result without running anything, and the source stays clean. @@ -17,7 +19,7 @@ The static snapshot is a point-in-time artifact. If an external service changes, --- -## Writeback: keep the result in the source +Writeback: keep the result in the source. For an exploratory or audit document, pair `foreign` with `lib/writeback`. `writeback.record` writes a keyed output slot next to the call. The slot is visible in the Markdown source, can be reviewed in a diff and can be committed with the document. @@ -27,12 +29,28 @@ For an exploratory or audit document, pair `foreign` with `lib/writeback`. `writ | writeback.record | Persist that value in a named slot | | git diff | Review the changed result like any other document change | -The checked-in runnable example is [examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md). Run it with `marqdo run examples/foreign-writeback/index.mq.md`; it writes a `total` slot containing `950` directly below the `writeback.record` call. Re-running replaces only that keyed slot. +A real writeback in this page. + +This page is itself the runnable example. The code fence below is ordinary Marqdo data; `foreign.run` executes it, then `writeback.record` writes the `total` slot into this source file. + +`写回代码` = +```python +print(950) +``` + +**结果 = > foreign.run code=`写回代码`** + +**> writeback.record value=`结果` key="total"** + + +The generated slot is directly below that call. Re-running the page replaces only the `total` slot; it does not duplicate it. Writeback is explicit. It is not hidden kernel serialization, does not persist arbitrary kernel memory, and does not touch a file unless the document calls it. --- -## Choosing +Choosing. For published user docs, use the static snapshot. For a living report that must keep the latest run result in the `.mq.md` itself, use writeback. Both can coexist in one repository: static pages for readers, writeback examples for authors and audits. diff --git a/public/features/21-持久化.mq.md b/public/features/21-持久化.mq.md index fb75bbf..6a751de 100644 --- a/public/features/21-持久化.mq.md +++ b/public/features/21-持久化.mq.md @@ -1,6 +1,8 @@ --- title: 外联执行结果的持久化 description: 静态快照与自写回 —— 外联结果在进程退出后如何保留 +导入 外联:lib/外联.mq.md +import writeback:lib/writeback.mq.md --- # main @@ -9,7 +11,7 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如 --- -## 静态快照:发布结果 +静态快照:发布结果。 `marqdo view output` 执行文档单元,并把真实输出嵌入生成的 HTML。`.mq.md` 源码不会被修改。这是用户文档、评审和稳定链接的默认选择:读者不需要运行任何东西就能看到结果,源码保持干净。 @@ -17,7 +19,7 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如 --- -## 自写回:把结果留在源码里 +自写回:把结果留在源码里。 对于探索性或审计型文档,把 `外联` 和 `lib/writeback` 搭配使用。`writeback.record` 会在调用点附近写入带 key 的输出槽位。槽位在 Markdown 源码中可见,可以在 diff 中审阅,也可以随文档提交。 @@ -27,12 +29,28 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如 | writeback.record | 把该值持久化到命名槽位 | | git diff | 像审阅普通文档改动一样审阅结果 | -可运行示例已经放在仓库里:[examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md)。运行 `marqdo run examples/foreign-writeback/index.mq.md`,它会在 `writeback.record` 调用下方写入包含 `950` 的 `total` 槽位。再次运行只替换这个 keyed 槽位。 +这一页本身就是完整示例。 + +这一页就是可运行的示例。下面的代码围栏是普通 Marqdo 值;`外联.运行` 执行它,然后 `writeback.record` 把 `total` 槽位写进本页源码。 + +`写回代码` = +```python +print(950) +``` + +**结果 = > 外联.运行 代码=`写回代码`** + +**> writeback.record value=`结果` key="total"** + + +生成的槽位就在这次调用下方。再次运行只替换 `total` 槽位,不会重复添加。 自写回是显式动作。它不是隐藏的内核序列化,不持久化任意内核内存,也不会在文档没有调用时修改文件。 --- -## 如何选择 +如何选择。 面向用户的发布文档用静态快照;需要把最新执行结果留在 `.mq.md` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。