View:叙述面标注缺口(prose annot gaps)
定位:对既有文档面设计的缺口专章——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
1. 为何「改了却几乎没变化」
| 原因 |
说明 |
| 错二进制 |
PATH 上的 marqdo 可能仍是旧版(如 1.3.0);改动在源码 / ./target/debug/marqdo。验收必须用 cargo build && ./target/debug/marqdo view … |
| Chip 被溢出藏掉 |
同 band 堆多帧 return/print/who;MAX_VISIBLE_ANNOTS=4 把当前帧的 who 打成 annot-chip-overflow(display:none);帧切换不重算溢出 |
| L-leader 几何错位 |
initAnnotLeaders 里 y0=0 只在 .annot-band 顶画短折,连不到上方 underline;窄屏或 chip>4 时整段关掉 leaders |
| 旧静态快照 |
gh-pages / 旧 view output 不会自动刷新 |
2. 目标视觉语法(既有,不新造)
锚定 view-document-annotations.md §3:
3. 管线
| 步骤 |
位置 |
| CLI / 导出 |
src/main.rs · src/view/mod.rs · src/view/output.rs |
| Capture + Call 事件 |
src/interp.rs |
| Annot 组装 |
src/view/annot.rs build_view_annots |
| 文档面 HTML |
src/view/document.rs |
| 卡片 chrome |
src/view/render.rs render_*_assign_card |
| CSS / leader JS |
src/view/html.rs |
4. 四条用户问题 → 根因 → 验收
复现源:public/00-welcome.mq.md · public/00-欢迎.mq.md
对照金样:tests/view/document-annot-demo.mq.md · tests/markup-v03/inc-prose.mq.md
P1 — 叙述与代码同段时信息不显示
|
|
| 现象 |
underline 在,chip / 连线弱或无 |
| 根因 |
html.rs initAnnotLeaders:y0=0 相对 band;document.rs MAX_VISIBLE_ANNOTS 把当前帧 chip 溢出;PATH 旧 CLI |
| 目标 |
同 inc-prose:underline + L-leader(从锚点底到 chip)+ 可见 chip |
| 验收 |
./target/debug/marqdo view public/00-welcome.mq.md:主文 **greet…** 与 ## greet 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
P2 — 函数内变量不显示
|
|
| 现象 |
`who` 有浅蓝 underline,无值 chip |
| 根因 |
bind chip 存在但带 annot-chip-overflow;applyCallFrame 只 hidden 非选中帧,不解除当前帧 overflow |
| 目标 |
选中调用帧时常显 who · print · return 各一枚 |
| 验收 |
切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
P3 — ```text 渲染不一致
|
|
| 现象 |
变成内联 text marqdo ext add…,无卡片 |
| 根因 |
Comment 围栏若进 flush_para → join(" ") → pulldown 当 inline code;应走 render_narrative_fence |
| 目标 |
与 bound python 同 .code-card chrome(badge + pre.code-body),无 Run/foot |
| 验收 |
welcome install 段:data-lang="text" + 两行 marqdo ext add;无 <code>text marqdo |
P4 — 函数引用 / 代码卡未渲染
|
|
| 现象 |
**greet who=…** 无结果;或 hi python 只见头/Run、不见源码 |
| 根因 |
同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
| 目标 |
主文两 greet 各有 call chip(stdout 摘要);hi = render_code_assign_card head→body→foot;静态藏 Run |
| 验收 |
两枚 greet mark 均有非空 data-annot-id;code-body 含 hello-from-python;MARQDO_VIEW_LIVE=false 无 Run 按钮 |
call_id 语义(写死)
| 位置 |
call_id |
主文 **greet…** 的 call chip |
入口帧(# main 的 call);结果为 stdout/返回摘要 |
## greet 体内 print / who / return |
callee 的 CallFrame id;跟函数标题旁 picker |
5. 修复约定(实现红线)
- 帧感知密度:band 内按选中
call_id 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + layoutAll()。
- Leader 容器:提升到
.doc-block(prose + band);y0 = 锚点底相对 block;按锚点 x 排序再画线。
- 卡片:只复用 Browse
render_*_assign_card / render_narrative_fence + html.rs .code-* / .formula-card;本波不改 Debug AST 路径(除非回归红)。
- 静态 Run:
MARQDO_VIEW_LIVE=false 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
- 非目标:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
6. 验收命令
7. 修订历史
| 日期 |
说明 |
| 2026-10-15 |
初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
| 2026-10-15 |
L-leader 拥挤/消失:同跨度多帧 chip 共用 annot id;可见 chip 按锚点 x 重排;leader 挂 doc-block |
| 2026-10-15 |
L-leader 黑线碎段:JS border*: "1.5px solid" 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
| 2026-10-15 |
L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |