From d5a9301c7fdcf423f22fa136a5f3831e6c2c903f Mon Sep 17 00:00:00 2001 From: cflmy Date: Mon, 14 Sep 2026 13:32:17 +0800 Subject: [PATCH] docs(public): finish stdlib bracket-call demos and fix import returns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prefer [lib.fn] in remaining public/stdlib samples, correct italic returns in structure import modules, and keep lib/系统 narration from starting with backticks. Co-authored-by: Cursor --- .cursor/skills/marqdo-dev/SKILL.md | 12 ++++++------ doc/roadmap/lib-ext-code-as-docs.md | 2 ++ lib/系统.mq.md | 2 +- public/stdlib/foreign.mq.md | 2 +- public/stdlib/json.mq.md | 4 ++-- public/stdlib/math.mq.md | 8 ++++---- public/stdlib/net.mq.md | 2 +- public/stdlib/plugin.mq.md | 4 ++-- public/stdlib/sys.mq.md | 4 ++-- public/stdlib/text.mq.md | 4 ++-- public/stdlib/外联.mq.md | 2 +- public/stdlib/插件.mq.md | 4 ++-- public/stdlib/数学.mq.md | 8 ++++---- public/stdlib/文本.mq.md | 4 ++-- public/stdlib/系统.mq.md | 4 ++-- public/stdlib/网络.mq.md | 2 +- public/structure/import/main.mq.md | 2 +- public/structure/import/utils.mq.md | 6 ++++-- public/structure/import/主.mq.md | 2 +- public/structure/import/工具.mq.md | 6 ++++-- 20 files changed, 45 insertions(+), 39 deletions(-) diff --git a/.cursor/skills/marqdo-dev/SKILL.md b/.cursor/skills/marqdo-dev/SKILL.md index 49cfbbe..289e113 100644 --- a/.cursor/skills/marqdo-dev/SKILL.md +++ b/.cursor/skills/marqdo-dev/SKILL.md @@ -63,22 +63,22 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex **Single dynamic key** — one `table.put` (or a helper), not a json chain: ```markdown -*`set_text` = > table.put in=None at="#log" value=msg* -**> table.put in=None at="set_text" value=set_text** +**`set_text` = table.put in=None at="#log" value=msg** +**table.put in=None at="set_text" value=set_text** ``` Better still — call a named helper: ```markdown -**> browser.set_text sel="#log" text=msg** +**browser.set_text sel="#log" text=msg** ``` ### 3. Bad pattern (do not write) ```markdown -*`ret` = > json.set map=None key="set_text" value=…* -*`ret` = > json.set map=ret key="canvas" value=…* -*`cmds` = > json.append list=cmds item=c0* +**`ret` = json.set map=None key="set_text" value=…** +**`ret` = json.set map=ret key="canvas" value=…** +**`cmds` = json.append list=cmds item=c0** ``` ## Writing application `.mq.md` diff --git a/doc/roadmap/lib-ext-code-as-docs.md b/doc/roadmap/lib-ext-code-as-docs.md index 36984b1..3dfa74b 100644 --- a/doc/roadmap/lib-ext-code-as-docs.md +++ b/doc/roadmap/lib-ext-code-as-docs.md @@ -31,6 +31,7 @@ | **M7** | structure collection 金样改链接形;public/stdlib 括号调用例 | **done** | | **M8** | 教程第 9 章 + Skill examples → 链接取元 / v0.3 标记 | **done** | | **M9** | 教程其余章节(1–8、10–12、14)全面对齐 v0.3 + 链接取元 | **done** | +| **M10** | public/stdlib 剩余演示统一括号调用;public import 返回面修到 v0.3 | **done** | ## 2. 验收(出门) @@ -53,3 +54,4 @@ | 2026-09-14 | M7 structure collection 金样 + stdlib 括号调用例 | | 2026-09-14 | M8 教程 + Skill examples 同步 | | 2026-09-14 | M9 教程全书对齐 v0.3 标记与链接取元 | +| 2026-09-14 | M10 public/stdlib 括号调用扫尾 + import 返回面 | diff --git a/lib/系统.mq.md b/lib/系统.mq.md index 0583c91..22fa46f 100644 --- a/lib/系统.mq.md +++ b/lib/系统.mq.md @@ -53,7 +53,7 @@ description: 中文系统包装(加载环境 可选 路径=) 运行子进程。默认返回退出码(整数)。 -`捕获=True` 时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。 +当捕获为真(`捕获=True`)时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。 在 `**…**` 内优先写裸变量 `参数=参数`;`` 参数=`参数` `` 亦可。 diff --git a/public/stdlib/foreign.mq.md b/public/stdlib/foreign.mq.md index bf34afd..4166a65 100644 --- a/public/stdlib/foreign.mq.md +++ b/public/stdlib/foreign.mq.md @@ -15,6 +15,6 @@ print("hello-from-python") Default command is python (Windows) or python3 (Unix). Override with set_cmd, env MARQDO_FOREIGN_PYTHON, or the command box in live view. Failures ask you to check that configuration. -**`out` = > foreign.run code=`hi` ** +**`out` = [foreign.run] code=`hi`** > print text=`out` diff --git a/public/stdlib/json.mq.md b/public/stdlib/json.mq.md index 0835f34..7519317 100644 --- a/public/stdlib/json.mq.md +++ b/public/stdlib/json.mq.md @@ -10,8 +10,8 @@ Shared JSON helpers for EN and ZH docs. Prefer parse, stringify, and quote. Build maps with tables or table.put — not json.set chains. **`obj` = [json.parse] text="{}"** -**`ty` = > type `obj`** +**`ty` = [type] `obj`** **打印 内容=`ty`** -**`out` = > json.stringify value=`obj`** +**`out` = [json.stringify] value=`obj`** **打印 内容=`out`** diff --git a/public/stdlib/math.mq.md b/public/stdlib/math.mq.md index e10a8e4..a922977 100644 --- a/public/stdlib/math.mq.md +++ b/public/stdlib/math.mq.md @@ -21,18 +21,18 @@ Plotting (already in the library): plot / plot_points / plot_conic return SVG te diff / simplify / expand / partial subs return formula values so you can chain (e.g. differentiate twice, then plot or eval). -**`ty` = > type `f`** +**`ty` = [type] `f`** > print text=`ty` -**`df` = > math.diff formula=`f` var="x"** +**`df` = [math.diff] formula=`f` var="x"** > print text=`df` -**`roots` = > math.solve formula=`f` var="x"** +**`roots` = [math.solve] formula=`f` var="x"** > print text=`roots` -**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3** +**`_svg` = [math.plot] formula=`f` var="x" min=-3 max=3** > print text=plot-ok diff --git a/public/stdlib/net.mq.md b/public/stdlib/net.mq.md index 2e80add..7bfcb03 100644 --- a/public/stdlib/net.mq.md +++ b/public/stdlib/net.mq.md @@ -8,6 +8,6 @@ import net:lib/net.mq.md Import lib/net.mq.md. Functions: http_get, http_post, http_post_sse, openai_sse_parse, http_request, url_encode. HTTPS and optional headers= map are supported. Default post content-type is JSON. `http_post_sse` / `openai_sse_parse` return OpenAI chat stream event lists (`delta` / `done`). -**`e` = > net.url_encode text="hello world"** +**`e` = [net.url_encode] text="hello world"** > print text=`e` diff --git a/public/stdlib/plugin.mq.md b/public/stdlib/plugin.mq.md index ecf2de0..40e814c 100644 --- a/public/stdlib/plugin.mq.md +++ b/public/stdlib/plugin.mq.md @@ -8,9 +8,9 @@ import plugin:lib/plugin.mq.md Import lib/plugin.mq.md. Functions: load(path), unload(), list(). After load, registered plugin names are callable like other functions. C ABI: include/marqdo_abi.h — see doc/design/ext-abi.md. Path must stay under the program sandbox (cwd / fs root). -**`names` = > plugin.list ** +**`names` = [plugin.list]** -**`n` = > len `names` ** +**`n` = [len] `names`** 1. `n` >= 0 > print text=plugin-ok diff --git a/public/stdlib/sys.mq.md b/public/stdlib/sys.mq.md index 86e8bed..e3cfe3e 100644 --- a/public/stdlib/sys.mq.md +++ b/public/stdlib/sys.mq.md @@ -8,9 +8,9 @@ import sys:lib/sys.mq.md Import lib/sys.mq.md. Functions: env_get, env_set, load_dotenv(optional path), args, cwd, exit(code), exec(cmd), stream_publish(event). load_dotenv does not override existing variables. Under view, exit soft-fails instead of killing the process. `stream_publish` feeds the view SSE EventBus. -**`d` = > sys.cwd ** +**`d` = [sys.cwd]** -**`n` = > len `d` ** +**`n` = [len] `d`** 1. `n` > 0 > print text=cwd-ok diff --git a/public/stdlib/text.mq.md b/public/stdlib/text.mq.md index 8295d2f..2509e44 100644 --- a/public/stdlib/text.mq.md +++ b/public/stdlib/text.mq.md @@ -11,6 +11,6 @@ Import lib/text. Bracket path or classic dotted calls both work. **`t` = [text.str_trim] s=" marqdo "** **打印 内容=`t`** -**`parts` = > text.str_split s="a,b,c" sep=","** -**`j` = > text.str_join xs=`parts` sep="-"** +**`parts` = [text.str_split] s="a,b,c" sep=","** +**`j` = [text.str_join] xs=`parts` sep="-"** **打印 内容=`j`** diff --git a/public/stdlib/外联.mq.md b/public/stdlib/外联.mq.md index a7877dd..36bfe51 100644 --- a/public/stdlib/外联.mq.md +++ b/public/stdlib/外联.mq.md @@ -15,6 +15,6 @@ print("hello-from-python") 默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。 -**`out` = > 外联.运行 代码=`hi` ** +**`out` = [外联.运行] 代码=`hi`** > print text=`out` diff --git a/public/stdlib/插件.mq.md b/public/stdlib/插件.mq.md index 79b717f..5407246 100644 --- a/public/stdlib/插件.mq.md +++ b/public/stdlib/插件.mq.md @@ -8,9 +8,9 @@ description: 加载可选共享库(.dll / .so / .dylib) 导入 lib/插件.mq.md。函数:加载(路径)、卸载()、列出()。加载后,插件注册的名称可像普通函数一样调用。C 契约见 include/marqdo_abi.h 与 doc/design/ext-abi.md。路径须落在程序沙箱内。 -**`names` = > 插件.列出 ** +**`names` = [插件.列出]** -**`n` = > 长度 值=`names` ** +**`n` = [长度] 值=`names`** 1. `n` >= 0 > 打印 内容=插件就绪 diff --git a/public/stdlib/数学.mq.md b/public/stdlib/数学.mq.md index 0bc9660..c6e5140 100644 --- a/public/stdlib/数学.mq.md +++ b/public/stdlib/数学.mq.md @@ -21,18 +21,18 @@ $$ 求导 / 化简 / 展开 / 未完全数值化的代入仍返回 formula,可继续链式调用(例如求二阶导后再绘图或求值)。 -**`ty` = > type `f`** +**`ty` = [type] `f`** > print text=`ty` -**`df` = > 数学.求导 formula=`f` var="x"** +**`df` = [数学.求导] formula=`f` var="x"** > print text=`df` -**`roots` = > 数学.求解 formula=`f` var="x"** +**`roots` = [数学.求解] formula=`f` var="x"** > print text=`roots` -**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3** +**`_svg` = [数学.绘图] formula=`f` var="x" min=-3 max=3** > print text=plot-ok diff --git a/public/stdlib/文本.mq.md b/public/stdlib/文本.mq.md index d3998d6..cc8eecb 100644 --- a/public/stdlib/文本.mq.md +++ b/public/stdlib/文本.mq.md @@ -11,6 +11,6 @@ description: 去空白、拆分、拼接(代码即文档试点) **`t` = [文本.去空白] s=" marqdo "** **打印 内容=`t`** -**`parts` = > 文本.拆分 s="甲,乙,丙" sep=","** -**`j` = > 文本.拼接 xs=`parts` sep="-"** +**`parts` = [文本.拆分] s="甲,乙,丙" sep=","** +**`j` = [文本.拼接] xs=`parts` sep="-"** **打印 内容=`j`** diff --git a/public/stdlib/系统.mq.md b/public/stdlib/系统.mq.md index 5a34439..9175ee4 100644 --- a/public/stdlib/系统.mq.md +++ b/public/stdlib/系统.mq.md @@ -8,9 +8,9 @@ description: 环境变量、dotenv、工作目录、参数、退出、执行 导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。 -**`d` = > 系统.工作目录 ** +**`d` = [系统.工作目录]** -**`n` = > 长度 值=`d` ** +**`n` = [长度] 值=`d`** 1. `n` > 0 > 打印 内容=工作目录就绪 diff --git a/public/stdlib/网络.mq.md b/public/stdlib/网络.mq.md index c02b4cf..78f80bf 100644 --- a/public/stdlib/网络.mq.md +++ b/public/stdlib/网络.mq.md @@ -8,6 +8,6 @@ description: HTTP(S) 与地址编码 导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。 -**`e` = > 网络.编码地址 内容="你好"** +**`e` = [网络.编码地址] 内容="你好"** > 打印 内容=`e` diff --git a/public/structure/import/main.mq.md b/public/structure/import/main.mq.md index b839189..7c14f0c 100644 --- a/public/structure/import/main.mq.md +++ b/public/structure/import/main.mq.md @@ -10,7 +10,7 @@ In the YAML header, `import utils:utils.mq.md` imports a sibling module and bind Bind a return value, print it, then call greet: -**`y` = > utils.add_one n=41** +**`y` = [utils.add_one] n=41** > print text=`y` diff --git a/public/structure/import/utils.mq.md b/public/structure/import/utils.mq.md index a25423c..5c76ec1 100644 --- a/public/structure/import/utils.mq.md +++ b/public/structure/import/utils.mq.md @@ -1,14 +1,16 @@ --- title: Utility module -description: Imported by main; bold is a return value +description: Imported by main; italic is return; print for side effects --- ## add_one + `n` -**`n` + 1** +*n + 1* ## greet + `who` > print text=Hello, `who`! + +*None* diff --git a/public/structure/import/主.mq.md b/public/structure/import/主.mq.md index d9366e6..fb700cc 100644 --- a/public/structure/import/主.mq.md +++ b/public/structure/import/主.mq.md @@ -10,7 +10,7 @@ description: frontmatter 导入 bind:路径.mq.md 绑定返回值、打印,再调用问候: -**`y` = > 工具.加一 n=41** +**`y` = [工具.加一] n=41** > 打印 内容=`y` diff --git a/public/structure/import/工具.mq.md b/public/structure/import/工具.mq.md index 2cda1b4..ae24097 100644 --- a/public/structure/import/工具.mq.md +++ b/public/structure/import/工具.mq.md @@ -1,14 +1,16 @@ --- title: 工具模块 -description: 被 main 导入;粗体为返回值 +description: 被 main 导入;斜体为返回;副作用用打印 --- ## 加一 + `n` -**`n` + 1** +*n + 1* ## 问候 + `谁` > 打印 内容=你好,`谁`! + +*无*