9.3 KiB
撰写风格与格式规范
写工程文件时除了字段对、能编过，还要满足下面这些风格与排版约束。textbook.typ、
stmt.typ、proof.typ、problem.typ、solution.typ 和 sop.typ 的内容都要遵守。
阅读样例 samples.md 里收录的好片段。本文件给方法论与红线，samples.md 给 具体的"写成那样就对"的例子。两份配合看。
核心思想：物理逻辑驱动行文
讲义和大纲的本质差，是讲义靠物理因果链把段落串起来，大纲靠编排话把条目列起来。 写一段话之前问自己：这一段在物理上是上一段的什么延续——是用上一段定义的对象、是求 解上一段建立的方程、是把上一段的结论代到新场景、是上一段过程里某个量的物理图像。如果 回答得出，段与段就是连贯的物理推进；如果答不出，只是凭"我下面想讲 X"在串，那这一段就 是大纲风。
样例 [简正模 19.1.1] 的推进顺序——动能的一般形式 → 二阶展开 → 矩阵化 → 对角化引入新 广义坐标——每一步都是上一步的物理延续。我们写 textbook 要争取做到同样的连贯性。
写作视角
教材的对象是学生。视角是教材作者在向学生陈述物理本身，不是教研团队在讨论怎么讲这门 课。前者用第一人称复数加陈述句，后者用讲师对自己的指令。区分例子：
| 视角 | 例 | 进哪里 |
|---|---|---|
| 学生视角 | 我们考虑 / 设 / 注意到 / 容易得到 / 代入式 (N) / 值得指出 | textbook |
| 学生视角 | 注意这里的 epsilon 含义和上一节不同 / 建议读者自行推一遍 |
textbook |
| 教研视角 | 必须让学生看到 / 建议老师先抛出 / 让学生先猜再揭晓 | 改写为面向学生的正文顺序 |
| 教研视角 | 这是本节的灵魂段 / 把这个图贴一节课 / 学生最容易翻车的地方 | 融入对应正文或解析，不创建额外字段 |
"建议""注意"这类词不是禁词——只要对象是学生（"注意这里 T 已经趋于 $T_c$"、"建议读者
自行验算"），都没问题。判断标准始终是对象是不是学生。
内容归宿判定
每一句话写下来之前先问归谁。
进 textbook：物理设置、定义、推导、结论、对结论的客观评议（量级、适用范围、与已知
结论的对照、反直觉之处、可能误用的边界）、必要的举例与模型归纳、本节定位（如果 outline
的章首"说明"明确要求让学生有一个 general 感受，那就保留——但要用陈述物理的语气，例如
"sigma 是界面性质而非液面专有"，不要用陈述教研策略的语气，例如"本节是大而全的建模专题"）。
当前 cph 0.0.2 没有 commentary / instruction 字段。真正影响理解的易错点应改写为面向学生
的 textbook.typ、proof.typ 或 solution.typ；只对教师有意义的内部动作建议不进入工程。
最常见的错误是把 outline 描述里"讲解策略"那段原样落到 textbook 里。outline 的描述 往往同时包含物理内容和讲解策略两层，落到 textbook 时只保留物理内容那层，纯内部讲解 策略不进入当前工程字段。
文风：理工男、性冷淡
行文应当冷静、客观、信息密度高。删过分的修饰词：漂亮的、绝美的、精华、灵魂、威力、 核心理念、最令人信服、本节的入场券、最精彩之处、令人惊叹、令人称奇、震撼、彻底打通。 保留必要的客观评议，例如反直觉的、值得指出的、量级正确的、与实测相符、超出本节范围、 精度有限。客观评议不带情感色彩。
修饰语的判定标准是：拿掉之后物理陈述是否还成立。如果拿掉后陈述完整，那这个修饰语就是 多余的。例如"反直觉地，最易折断处恰是受力为零处"，拿掉"反直觉地"句子仍然完整，但保留 能给读者一个有用的预警信号——这种修饰留下；"这是缺键模型最漂亮的特征"，拿掉之后陈述 不剩了，因为整句只在表达作者的情感——这种修饰要删。
关于"预告"与"回扣"
物理上确实需要前后引用时，用最简洁的方式说出来，不做铺垫：
- ✅ "下一节将用同一组论证处理固体表面。"
- ✅ "由式 (N)，
L_m随T单调下降。" - ❌ "这里埋一个伏笔——固体表面那一节会回扣，到时学生会看到……"
- ❌ "至此从微观键能到宏观浸润的整条物理链条全部建立。"
判定标准：陈述未来内容用陈述句、不带情感、不带"伏笔""回扣""一里"等编排语言；要回引 前文时直接用式号或一句"由前面的讨论"。
proof 与 solution 也走纯推导风
proof / solution 是一连串公式与最小衔接词，不是讲解。一段证明里只允许出现： 公式、用于把上一行连到下一行的最短连接词（代入、由、化简得、即得、解出、注意到、令）、 以及一两句必要的物理含义说明。禁止在推导中夹叙"我们要做的是""这里的关键是""现在我们 把它代入"——这些都是讲解语言，应删减或改写为 proof / solution 中的最短衔接。
衔接词举例：
由 @骨架公式，
$ sigma_(L G) = Delta U dot n_s . $
代入 @缺键-亏损能 与 @缺键-面密度 得
$ sigma_(L G) = (1 - zeta) L_m / N_A dot (rho N_A / mu)^(2\/3) , $
化简即得 @缺键一般式。
注意几个特征：每一步都有式号引用、连接词不超过两个汉字、没有"先做 A 再做 B"的元叙述、 也没有对结果的情感评议。
如果证明确实需要分步走，可以用"第一步""第二步"或者直接用陈述把每一步定位——但每一步 内部仍然是公式驱动。看 samples.md 的 proof 范例。
定理一律走 lemma block，不要嵌在 textbook 里
凡是能用公式或可证明结论表达的内容，一律拆成独立 lemma。textbook 只负责把读者引到那个 定理跟前，不要在 textbook 里复述定理结论本身。
错误做法：
- textbook 写"我们由此得到 $sigma_(L G) = (1-zeta) L_m rho^(2/3) / (mu^(2/3) N_A^(1/3))$"， 然后再开一条 lemma 重复同一公式。
正确做法：
- textbook 写到"代入骨架公式即得液气界面张力的解析式"为止，立刻接 lemma block。lemma 的 stmt 给完整结论。
排版规则
不要对任何知识点、概念、公式或专有名词做加粗处理。Typst 里加粗的写法是 bold(...)
（不是 *...*，星号是 markdown 的写法，与 typst 加粗语义混在一起容易踩坑）。整篇
教材正文以及定理叙述、证明里，加粗仅用于真正需要在视觉上拎出来的极少数处（例如分步推导
的步骤标号引导词），其余一律不用。
引入概念时不要在中文名后面加括号附上英文。英文术语只在该术语必须以英文形式被引用（如 "LJ 势能"中的"LJ"）或确有歧义需要消歧时才出现，否则只用中文。
数学排版（Typst 语法）
公式下标只用阿拉伯数字、希腊字母或单个英文字母，禁止用一个有含义的英文词或缩写当下标。
入射量用 i、出射量用 o、表面用 s、体相用 b 等，单字母即可，不要写 "in" /
"out" / "surf" / "bulk"。
求导符号里的 d 一定要用 Typst 的 dif 让它显示成正体。不要直接写 d x——那会被排
成斜体的 d。例如：
sigma dif A
integral_0^L F dif x
(dif gamma) / (dif epsilon)
偏导符号用 partial，不要用 diff。diff 是 Typst 旧版本的偏导写法，新版本已经
deprecated，写出来会触发 stderr 警告。
(partial F) / (partial A)
((partial sigma) / (partial T))_(A, V)
虚数单位的 i 同理要用正体。Typst 里直接写 i 是斜体，需要先在文件开头定义一次
#let ii = math.upright("i")
之后所有用到虚数的地方都写 ii，例如 e^(ii omega t)。
加粗的数学符号（如矢量）用 bold(...)，不要用 markdown 风的 *...*。例如：
bold(F) = m bold(a)
nabla times bold(E) = - (partial bold(B)) / (partial t)
正负号写 plus.minus，不要写 pm——后者在 Typst 数学里不存在。例如：
x = plus.minus sqrt(b^2 - 4 a c)
Typst 不存在 varepsilon。Epsilon 字母只有 epsilon 与 epsilon.alt，按需选用。
其它常用 Typst 数学排版备忘
- 标量斜体、矢量加粗（用
bold(...)）、单位与函数名正体（如op("sin")已内置，直接 写sin x、cos x、ln x即可）。 - 公式编号通过
<标签>标记，引用用@标签。同一课程内标签必须全局唯一。 - 数学块用
$ ... $（块状）或行内$...$。块状公式两端的$要有空格隔开，否则会被 解析为行内。 - 微分元等正体粒子（除
dif外的几个）：partial（偏导符号已经是正体）、单位向量带 hat 用hat(x)。 - 希腊字母大小写区分：
sigma/Sigma、gamma/Gamma。
如有更复杂的排版需求（如 cases 分支、矩阵、长公式断行）需要用到却不确定写法，停下来 问用户或查 Typst 文档；不要凭直觉用 LaTeX 语法塞进去——很多 LaTeX 控制序列在 Typst 里都不存在或语义不同。