feat(markup): code-as-docs narration surface (G1–G4) and drop --- body end
Treat --- as Markdown HR everywhere, end side-effect helpers with empty returns, and accept soft emphasis, float literals, and dynamic footnote keys so LLM-friendly .mq.md stays runnable. Ship the weekend coffee example plus gold fixtures. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
b5c07385e9
commit
5e74ff39f2
28 files changed
+799
-99
No files matched your search
@@ -0,0 +1,21 @@
|
||||
# 代码即文档 · 周末咖啡手账
|
||||
|
||||
可读可跑的 v0.3 样例:`.mq.md` 同时是说明文和程序。
|
||||
|
||||
```bash
|
||||
marqdo run examples/code-as-docs/index.mq.md
|
||||
```
|
||||
|
||||
## 这份样例在示范什么
|
||||
|
||||
| 习惯 | 写法 |
|
||||
|------|------|
|
||||
| 数据给人读 | GFM 表当菜单 / 订单 |
|
||||
| 步骤嵌在句子里 | `**总额 = 价 * 杯数**`、返回 `*总额*` |
|
||||
| 装饰性强调 | `**说明**` 不执行(见设计 G2) |
|
||||
| 段落分隔 | 顶层或体内的 `---` 只是分割线 |
|
||||
| 浮点 | `折扣`=0.85 |
|
||||
| 动态键 | `` 菜单[^`名`] `` |
|
||||
| 调用 | 粗体赋值右侧 **可省略 `>`**:`**摘要 = 结账摘要 …**`;输出可用 `**打印 内容=…**` |
|
||||
|
||||
相关设计:[code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md)、[markdown-mapping-v0.3.md](../../doc/design/markdown-mapping-v0.3.md) §6。
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: 代码即文档 · 周末咖啡手账
|
||||
description: >-
|
||||
一份可读可跑的周末手账:菜单是表,计价写在段落里,主流程像日记。
|
||||
展示叙述统一写法、装饰性强调、分隔线、浮点折扣、动态脚注键,以及粗体内免 `>` 的调用。
|
||||
---
|
||||
|
||||
本文件既是**说明**也是**程序**。人读得到段落与表格;机器执行嵌在叙述里的粗体步骤,并把斜体当作返回值。
|
||||
不必回避 Markdown 强调——不像代码的 `**说明**` 只是装饰。段落之间也可以用分隔线:
|
||||
|
||||
---
|
||||
|
||||
## 单价
|
||||
|
||||
一杯标价为`价`的饮品,默认`杯数`=1。先算**总额 = 价 * 杯数**,再返回*总额*。
|
||||
|
||||
## 会员折
|
||||
|
||||
会员单需要原价`原价`;门店默认八五折,写作`折扣`=0.85。
|
||||
先算**应付 = 原价 * 折扣**,再返回*应付*。
|
||||
|
||||
## 结账摘要
|
||||
|
||||
客人点了`品名`,单价`价`,杯数`杯数`=1;是否`会员`=False。
|
||||
|
||||
小计交给单价:**小计 = 单价 价=`价` 杯数=`杯数`**。
|
||||
|
||||
1. `会员`
|
||||
**实付 = 会员折 原价=`小计`**
|
||||
**标签 = "会员价"**
|
||||
2. *
|
||||
**实付 = 小计**
|
||||
**标签 = "原价"**
|
||||
|
||||
拼成一句给人对账的话,然后返回:
|
||||
|
||||
**文案 = 品名 + " ×" + 杯数 + " → " + 标签 + " " + 实付**
|
||||
*文案*
|
||||
|
||||
## 加一
|
||||
|
||||
对于输入`n`,执行**n=n+1**接着返回*n*。
|
||||
|
||||
# main
|
||||
|
||||
周末手账从一张菜单开始。数据用表格写——人一眼能读,程序把它当成字典:
|
||||
|
||||
`菜单` =
|
||||
|
||||
| 美式 | 拿铁 | 燕麦拿铁 |
|
||||
|------|------|----------|
|
||||
| 18 | 28 | 32 |
|
||||
|
||||
---
|
||||
|
||||
第一单:会员双杯拿铁。品名先记在变量里,再用动态键取价;粗体赋值右侧是调用时不必再写 `>`:
|
||||
|
||||
**名 = "拿铁"**
|
||||
**摘要 = 结账摘要 品名=`名` 价=菜单[^`名`] 杯数=2 会员=True**
|
||||
**打印 内容=`摘要`**
|
||||
|
||||
对照一单非会员美式——品名已知,静态键即可:
|
||||
|
||||
**对照 = 结账摘要 品名="美式" 价=菜单[^美式]**
|
||||
**打印 内容=`对照`**
|
||||
|
||||
---
|
||||
|
||||
也可以把今日订单写成行表。循环里把行字段直接传给结账,少一层临时变量:
|
||||
|
||||
`今日订单` =
|
||||
|
||||
| @ | 品名 | 单价 | 杯数 | 会员 |
|
||||
|---|------|------|------|------|
|
||||
| 1 | 燕麦拿铁 | 32 | 1 | True |
|
||||
| 2 | 美式 | 18 | 2 | False |
|
||||
|
||||
- [`行`](`今日订单`)
|
||||
**一行 = 结账摘要 品名=行[^品名] 价=行[^单价] 杯数=行[^杯数] 会员=行[^会员]**
|
||||
**打印 内容=`一行`**
|
||||
|
||||
最后用加一收个尾,确认叙述里的位置调用也通:
|
||||
|
||||
**试算 = 加一 41**
|
||||
**打印 内容=`试算`**
|
||||
Reference in new issue
Block a user