forked from EduCraft/curriculum-project-hub
183 lines
9.3 KiB
Markdown
183 lines
9.3 KiB
Markdown
## 撰写风格与格式规范
|
||
|
||
写工程文件时除了字段对、能编过，还要满足下面这些**风格与排版约束**。`textbook.typ`、
|
||
`stmt.typ`、`proof.typ`、`problem.typ`、`solution.typ` 和 `sop.typ` 的内容都要遵守。
|
||
|
||
阅读样例 [samples.md](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](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
|
||
里都不存在或语义不同。
|