docs(public): finish stdlib bracket-call demos and fix import returns

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 <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-14 13:32:17 +08:00
1 parent 34915e3b16
commit d5a9301c7f
20 files changed
+45 -39

No files matched your search

+6 -6
View File
@@ -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`
+2
View File
@@ -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 返回面 |
+1 -1
View File
@@ -53,7 +53,7 @@ description: 中文系统包装(加载环境 可选 路径=)
运行子进程。默认返回退出码(整数)。
`捕获=True` 时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。
当捕获为真(`捕获=True`)时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。
在 `**…**` 内优先写裸变量 `参数=参数`;`` 参数=`参数` `` 亦可。
+1 -1
View File
@@ -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`
+2 -2
View File
@@ -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`**
+4 -4
View File
@@ -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
+1 -1
View File
@@ -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`
+2 -2
View File
@@ -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
+2 -2
View File
@@ -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
+2 -2
View File
@@ -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`**
+1 -1
View File
@@ -15,6 +15,6 @@ print("hello-from-python")
默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。
**`out` = > 外联.运行 代码=`hi` **
**`out` = [外联.运行] 代码=`hi`**
> print text=`out`
+2 -2
View File
@@ -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
> 打印 内容=插件就绪
+4 -4
View File
@@ -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
+2 -2
View File
@@ -11,6 +11,6 @@ description: 去空白、拆分、拼接(代码即文档试点)
**`t` = [文本.去空白] s=" marqdo "**
**打印 内容=`t`**
**`parts` = > 文本.拆分 s="甲,乙,丙" sep=","**
**`j` = > 文本.拼接 xs=`parts` sep="-"**
**`parts` = [文本.拆分] s="甲,乙,丙" sep=","**
**`j` = [文本.拼接] xs=`parts` sep="-"**
**打印 内容=`j`**
+2 -2
View File
@@ -8,9 +8,9 @@ description: 环境变量、dotenv、工作目录、参数、退出、执行
导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。
**`d` = > 系统.工作目录 **
**`d` = [系统.工作目录]**
**`n` = > 长度 值=`d` **
**`n` = [长度] 值=`d`**
1. `n` > 0
> 打印 内容=工作目录就绪
+1 -1
View File
@@ -8,6 +8,6 @@ description: HTTP(S) 与地址编码
导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。
**`e` = > 网络.编码地址 内容="你好"**
**`e` = [网络.编码地址] 内容="你好"**
> 打印 内容=`e`
+1 -1
View File
@@ -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`
+4 -2
View File
@@ -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*
+1 -1
View File
@@ -10,7 +10,7 @@ description: frontmatter 导入 bind:路径.mq.md
绑定返回值、打印,再调用问候:
**`y` = > 工具.加一 n=41**
**`y` = [工具.加一] n=41**
> 打印 内容=`y`
+4 -2
View File
@@ -1,14 +1,16 @@
---
title: 工具模块
description: 被 main 导入;粗体为返回值
description: 被 main 导入;斜体为返回;副作用用打印
---
## 加一
+ `n`
**`n` + 1**
*n + 1*
## 问候
+ `谁`
> 打印 内容=你好,`谁`!
*无*