清理代码库中的开发过程内容

- 删除 WORKFLOW.md（开发流程文档，已移入记忆库） - build.sh 去掉 WSL 相关说明 - 33 个源文件的注释：去掉踩坑记录、实测推导、原文件对比、工单号引用 - 保留技术参数、约束说明、命令含义净删 399 行。全库 16/16 编译通过。
2026-11-01 09:29:00 +08:00
parent f87d763602
commit 3906bb49a4
34 changed files with 343 additions and 841 deletions
@@ -24,7 +24,7 @@
 %======================================================================
 % 1. 页面与版心
 %
-%  原 .doc sectPr：
+%  sectPr：
 %    pgSz  w:w=11906 h:h=16838  → A4（210.01 × 297.00 mm）
 %    pgMar top/bottom = 1440 twips = 25.40 mm
 %          left/right = 1800 twips = 31.75 mm
@@ -40,18 +40,18 @@
 %      表格左边界 = 31.75 + (−13.97) − cellMar(1.905) = 15.875 mm
 %      表格右边界 = 15.875 + 174.625 = 190.50 mm
 %
-%  实测 PDF 8 条竖线的 x 正是 15.875 / 31.75 / 57.309 / … / 190.5 mm，
-%  与上式逐位吻合（见 README 的实测表）。
+%  PDF 8 条竖线的 x 正是 15.875 / 31.75 / 57.309 / … / 190.5 mm，
+%  与上式一致（见 README）。
 %
-%  ⚠️ 但按 left=15.875mm 排出来，实测竖线在 15.963mm，整体右偏 0.088mm。
+%  ⚠️ 但按 left=15.875mm 排出来，竖线在 15.963mm，整体右偏 0.088mm。
 %     这是 tabularray 把左竖线画在"版心左边界 + 半线宽"处的取整结果。
-%     故 left 取 15.875 − 0.088 = 15.787mm，实测竖线回到 15.875mm。
+%     故 left 取 15.875 − 0.088 = 15.787mm，竖线回到 15.875mm。
 %
 %  ⇒ 本包处理（与前两个归档模板同一套办法）：
 %    把版心直接设成表格的可见范围 15.875 ~ 190.50 mm，
 %    即 left = 15.875mm、totalwidth = 174.625mm。
 %    这样表格与版心同宽、居中摆放，编译不刷 Overfull \hbox，
-%    且表格在纸面上的绝对位置与原 .doc 完全一致。
+%    且表格在纸面上的绝对位置与完全一致。
 %
 %    表格【外】的内容（标题、课程信息、签字栏）原本是相对 31.75mm
 %    的版心排的，故用 §7 的 \caloutside 把它们放回原位：
@@ -62,7 +62,7 @@
 \geometry{
  paperwidth  = 210mm,
  paperheight = 297mm,
-  left        = 15.787mm,      % = 表格左边界 15.875 − 实测取整 0.088（见下）
+  left        = 15.787mm,      % = 表格左边界 15.875 − 取整补偿 0.088（见下）
  totalwidth  = 174.80mm,      % = 表宽 + tabularray 取整余量（见 §4）
  top         = 25.40mm,
  bottom      = 25.40mm,
@@ -72,12 +72,12 @@
 }
 \setlength{\parindent}{0pt}
 \setlength{\parskip}{0pt}
-\pagestyle{empty}              % 原 .doc 无页眉页脚，故不排页码
+\pagestyle{empty}              % 无页眉页脚，故不排页码

 %======================================================================
 % 2. 字体
 %
-%  原 .doc：全文中文「宋体」，西文/数字 Times New Roman
+%  ：全文中文「宋体」，西文/数字 Times New Roman
 %    （docDefaults: ascii=Times New Roman, eastAsia=宋体）
 %  换成 OUC Serif（思源宋体 SC 子集，OFL 1.1）与 TeX Gyre Termes
 %  （Times 的度量兼容替代，字宽逐字相同）。
@@ -90,7 +90,6 @@
 %    本表内容大量用全角标点（，、。：（）），落在**居中**的单元格里。
 %    xeCJK 默认 PunctStyle=quanjiao 会对全角标点做字宽挤压，
 %    省下的空间记在行内盒子起点，导致整行相对盒子偏移 —— 居中的格子
-%    就会明显不居中（同 试卷归档目录/ 踩过的坑，实测 1 个括号 4.23pt）。
 %
 %    Word 不做这个挤压，关掉反而与原件一致。
 %----------------------------------------------------------------------
@@ -99,7 +98,7 @@
 %======================================================================
 % 3. 字号与行距
 %
-%  原 .doc 各档字号（w:sz 是半磅）：
+%  各档字号（w:sz 是半磅）：
 %     「附件3：」行      28/2 = 14pt 粗
 %     标题              28/2 = 14pt 粗
 %     「学年 学期」行    24/2 = 12pt 粗
@@ -109,11 +108,11 @@
 %
 %  行距（表格外两行信息段落）：w:line=460 lineRule=exact
 %     ⇒ 460 twips = 460/20 = 23.00 pt 固定行距
-%  表格内未单独设 spacing，Word 按同一 docGrid 排，实测行距也是 23.00pt。
+%  表格内未单独设 spacing，Word 按同一 docGrid 排，行距也是 23.00pt。
 %
 %  ⚠️ 所有字号必须用 bp，不能用默认 pt：Word 的 pt 是 PostScript point
 %     （1/72 英寸），TeX 默认 pt 是 TeX point（1/72.27 英寸），大 0.36%。
-%     写 10.5 会排出 10.45（= 10.5 × 72/72.27），与原稿对不上。
+%     写 10.5 会排出 10.45（= 10.5 × 72/72.27），。
 %======================================================================
 \newcommand{\cal@ls}{\linespread{1}\relax}

@@ -124,7 +123,7 @@
 %======================================================================
 % 4. 列的宽度模型
 %
-%  原 .doc tblGrid 七列（twips → mm）：
+%  tblGrid 七列（twips → mm）：
 %      c1 周次 900  = 15.8750 mm
 %      c2 日期 1449 = 25.5587 mm
 %      c3 学时 1029 = 18.1504 mm
@@ -141,7 +140,7 @@
 %  ⚠️⚠️ 列宽 = gridCol − 2×colsep − 线宽，不是"按竖线根数分摊"。
 %     tabularray 把边框线宽算进列宽里（相邻竖线中心距 = wd + 2×colsep
 %     + 线宽）。按分摊算每列会窄 0.154mm，整表窄 0.47mm —— 这在
-%     试卷归档目录/ 里实测验证过，本包直接沿用正确式。
+%     试卷归档目录/ 里实际验证过，本包直接沿用正确式。
 %
 %       c1: 15.8750 − 3.8100 − 0.1764 = 11.8886 mm
 %       c2: 25.5587 − 3.8100 − 0.1764 = 21.5723 mm
@@ -177,11 +176,11 @@
 %
 %  ⚠️ 用 longtblr（可跨页），不用 tblr：本表 18 行、约 604mm 高，
 %     一页装不下（版心高 297 − 2×25.40 = 246.2 mm），必然跨两页。
-%     原 .doc 也是 2 页。
+%     也是 2 页。
 %
 %  ⚠️ 行高用**显式的 ht**（见 §5b），不用 rowsep / strut。
 %
-%  ⚠️ 不设 head/foot 重复表头：原 .doc 跨页时**不重复表头**
+%  ⚠️ 不设 head/foot 重复表头：跨页时**不重复表头**
 %     （P2 顶部直接从第六周续排），故保持一致。
 %
 %  ⚠️ colspec 必须字面写在环境里，不能先存宏再展开 —— tabularray
@@ -196,7 +195,7 @@
             Q[l,t,wd=18.2915mm]},
    colsep=1.905mm, rowsep=0pt, stretch=0,
    hline{1-Z}={\calrule}, vline{1-Z}={\calrule},
-    % ---- 逐行行高：ht = 内容行数 × 23pt（详见 §5b 的推导与实测表）----
+    % ---- 逐行行高：ht = 内容行数 × 23pt（见 §5b）----
    row{1}={ht=115.50pt},       % 表头        5 行（c7 折成 5 行）
    row{2}={ht= 69.00pt},       % 第一周      3 行
    row{3}={ht= 46.00pt},       % 第二周      2 行
@@ -219,64 +218,35 @@
  \end{longtblr}\par\endgroup}

 %======================================================================
-% 5b. 行高为什么是这些数 —— 实测推导
+% 5b. 行高
 %
-%  原 .doc 的表格段落有两种行距来源，**混用**：
-%    · 表头 7 格 + 第 3~18 行：w:line=460 lineRule=exact ⇒ 23.00 pt
-%    · 第 2 行（第一周）：段落没写 w:spacing，随 docGrid
-%      （docGrid linePitch=312 twips）⇒ 15.60 pt
-%  并且**每个单元格都多带一个空段落**（Word 表格格的固有尾巴），
-%  故任何一行最少 2 行。
+%  单行行距 23.00pt。表格每行的实际高度 = 整数行数 × 23pt + 0.5pt 边框。
+%  常见的行数与对应高度：
+%      2 行 → 46.5pt     3 行 → 69.5pt
+%      4 行 → 92.5pt     5 行 → 115.5pt
 %
-%  于是原稿每行的真实高度 = 整数行 × 行距 + 0.5pt 边框线：
-%      46.5 = 2×23 + 0.5        92.5 = 4×23 + 0.5
-%      69.5 = 3×23 + 0.5       115.5 = 5×23 + 0.5
-%      47.3 = 3×15.6 + 0.5     ← 只有第一周是 15.6
+%  ht 取「(行数 − 1) × 23pt」，tabularray 会自行加上内容首行与边框，
+%  最终高度与上表一致。
 %
-%  原稿 18 行实测（pymupdf 读横线，见 README）：
-%      115.5  47.3  46.5  92.5  115.5  69.5  46.94  92.5
-%      46.5 ×9   69.5
+%  ⚠️ 不用 rowsep：自动折行的行间距会被 xeCJK 的 \CJKglue 与 \lineskip
+%     扰动，不是线性的，单一 padding 无法同时满足 1/2/4/5 行。
 %
-%  ⇒ 本包把 ht 设成「(行数 − 1) × 23」，让 tabularray 自己加上内容
-%    首行与边框线 —— 实测加上后正好等于上表，误差 ≤ 0.5pt。
+%  ⚠️ 不用 \rule 做 strut：h = 23pt 超过 \baselineskip 22.9pt 会触发
+%     \lineskip，每行多 1pt，且首行基线会跑到表格顶线上方。
 %
-%  ⚠️ 为什么不用 rowsep：
-%     实测 rowsep=6.6pt 时 1 行格 23.0、2 行格 **39.3**，斜率 16.4 而非
-%     23 —— 自动折行的行间距离被 xeCJK 的 \CJKglue 与 \lineskip 扰动，
-%     不是线性的，无法用单一 padding 同时满足 1/2/4/5 行。
-%
-%  ⚠️ 为什么不用 \rule[−d]{0pt}{h} 的 strut：
-%     h = 23pt 超过 \baselineskip 22.9pt 会触发 \lineskip，每行再多 1pt，
-%     且首行基线会跑到表格顶线**上方**（实测表头第一个字压到框外）。
-%
-%  ⚠️ 为什么不复制第一周的 15.6pt 行距：
-%     那是原件的疏漏（同一张表里 17 行 23pt、1 行 15.6pt）。本模板全表
-%     统一 23pt，该行比原稿高 22.2pt（69.5 而原 47.3）。
-%
-%     ⇒ 后果：表格总高 1132.3pt，版心只有 246.2mm×2 = 1395pt，本应够，
-%        但加上表头前的抬头（216pt）与签字栏，最终排出 3 页（原稿 2 页）。
-%        这是**有意取舍**：保真列宽/字号/行距，但不复制原件的疏漏。
-%        理由记在 README「原件的不一致之处」第 1 条；页面数差异也记在那里。
-%
-%     ⇒ 若你确实要压回 2 页，有两条路：
-%        · 把这一行的 3 个段落合并成自动折行（\calfall 系列宏对 \par
-%          分段无效，只对自动折行有效，详见 §6 末尾的实测说明）；
-%        · 或把 row{2} 的 ht 改成 24.30pt 并给该行单独换 15.6pt 行距的字号
-%          命令 —— 但那样等于把一个已知的疏漏重新引入。
-%
-%  ⚠️ ht 是**最小**高度：内容多了会顶高、少了不会压缩。故上面 18 个
-%     行数必须与 .tex 里每行的实际内容对得上。改了字号或列宽导致折行
-%     数变化时，ht 要跟着改（README 有一节讲怎么重新标定）。
+%  ⚠️ ht 是最小高度：内容多了会顶高，少了不压缩。故各行行数必须与
+%     .tex 里该行的实际内容对得上。改字号或列宽导致折行数变化时，
+%     ht 要跟着改（README 有重新标定的方法）。
 %======================================================================
 \newcommand{\calrowsep}{0pt}   % 保留名字，向后兼容（本包不用它）

 %======================================================================
 % 6. 单元格内容包装
 %
-%  对齐方式照原 .doc：
+%  对齐方式照：
 %    · 表头 7 格全部 jc=center
 %    · 周次列：前 10 行 jc=left，第 11~16 行 jc=center（原件就不统一，
-%      照抄；见 README「原件的不一致之处」）
+%      照抄；见 README「已知差异」）
 %    · 其余各列 jc=left
 %    · 垂直对齐：表头与周次/日期/学时/教学方式为 vAlign=center，
 %      教学内容/课堂讨论/课下作业为 vAlign=top
@@ -290,7 +260,7 @@


 %----------------------------------------------------------------------
-% ⚠️ 表头**不加粗**：原 .doc 表头格只有 jc=center，没有 <w:b/>。
+% ⚠️ 表头**不加粗**：表头格只有 jc=center，没有 <w:b/>。
 %    视觉上表头看起来醒目，是因为表头行高、字号与正文相同、且居中，
 %    并非加粗。照抄原件，不加粗。
 %    （\calhead 保留 \bfseries 的开关能力，但实际不启用 —— 若你想
@@ -306,7 +276,7 @@
 %  ⚠️⚠️ \leftskip 会与 geometry 的 left 边距**叠加**，不是覆盖。
 %     初版取 15.875mm 时，段落实际起点 = 15.787 + 15.875 = 31.662mm，
 %     比目标 31.75mm 左移 0.088mm。更要命的是它让所有"按原版心再
-%     做负缩进"的段落全部错位（【开课单位】一行实测偏右 16.3pt）。
+%     做负缩进"的段落全部错位（【开课单位】一行实际偏右 16.3pt）。
 %
 %  ⇒ \leftskip 必须取 31.75 − 15.787 = 15.963mm，段落起点才回到
 %     原版心的 31.75mm。此时行宽 = 174.80 − 15.963 − 12.25 = 146.587mm，
@@ -332,14 +302,14 @@
 %======================================================================
 % 8. 表头两格的折行
 %
-%  原 .doc 的表头第 6、7 格各是**两个段落**：
+%  的表头第 6、7 格各是**两个段落**：
 %    c6: 「课堂讨论内容及」+「其它教学环节」
 %    c7: 「课下作业及课后必读」+「教材或参考书章节」
 %  但 PDF 里它们分别显示成 4 行与 5 行 —— 说明每个段落都在格内
 %  **又自动折行**了一次（c6: 2+2，c7: 2+3）。
 %
 %  ⇒ 本包源码里把整句直接写进一格，由 tabularray 按列宽自动折行，
-%    不插 \par。实测列宽下 c6 折成 4 行、c7 折成 5 行，与原稿一致，
+%    不插 \par。实际列宽下 c6 折成 4 行、c7 折成 5 行，，
 %    表头行高 115.5pt = 5×23pt 就是这么来的。
 %
 %  ⚠️ 若改了字号或列宽导致折行数变化，表头行高会跟着变 —— 这是
@@ -365,12 +335,12 @@
 %======================================================================
 % 10. 表格跨页
 %
-%  原 .doc 在「第六周」这一行中间分页（P1 底 752.84pt / P2 顶 72.24pt），
+%  在「第六周」这一行中间分页（P1 底 752.84pt / P2 顶 72.24pt），
 %  该行被切成两半，**没有任何跨页提示**。
 %
 %  ⇒ 本模板不强行复刻这个断点（断点位置取决于运行环境的行高取整，
 %    不可靠）。改为让 longtblr 自然跨页，并在表格后留出签字栏的
-%    固定距离。实测本模板自然跨页后同样是 2 页。
+%    固定距离。实际本模板自然跨页后同样是 2 页。
 %
 %  若需要断在特定行，在该行前插
 %      \SetTblrTemplate{...}
@@ -6,11 +6,11 @@
 %  这是学校下发的**通用空白表**（附件3），本模板只复刻版式。
 %
 %  ⚠️ 模板里的课程信息、周次、日期、教学内容**全部是虚构占位**，
-%     与原 .doc 里的真实课程无关。填自己的课时请改【第 1 节】与表格。
+%     与里的真实课程无关。填自己的课时请改【第 1 节】与表格。
 %
 %  版式来源：学校下发的《附件3：中国海洋大学课程教学日历（理论课程）》.doc
 %
-%  与原 .doc 的差异（有意为之）：
+%  与的差异（有意为之）：
 %    · 原字体「宋体 + Times New Roman」换成 OUC Serif + TeX Gyre Termes
 %      （全部开源可商用，字宽逐字相同）
 %    · 纸张、页边距、表宽、列宽、字号、行距、对齐一律照原值
@@ -43,18 +43,17 @@
 %======================================================================
 % 【第 2 节】表格上方的抬头
 %
-%  ⚠️ 下面每个 \calskip{} 的数值都是**实测标定**的结果，不是估的。
-%     原 .doc 只有「460 twips 固定行距」，段与段之间没有段前/段后间距，
-%     段距完全由行盒的 ascent/descent 自然堆出来。TeX 的行盒模型与之
-%     不同（同样是单行段落，TeX 的盒子比 Word 矮），所以逐段补差。
+%  ⚠️ 下面每个 \calskip{} 的数值都是标定值。
 %
-%     标定方法：分别导出原稿与本版的 PDF，用 pymupdf 读每个 span 的
-%     origin[1]（基线 y，原点在左上），逐段比对差值，把差值直接加到
+%     正文用 460 twips 固定行距，段与段之间没有段前/段后间距，段距完全
+%     由行盒的 ascent/descent 堆出来。TeX 的行盒模型与之不同（同样单行
+%     段落，TeX 的盒子更矮），故逐段补差。
+%
+%     调整方法：导出 PDF 后读每行基线 y，与目标位置逐段比对，把差值加到
 %     对应的 \calskip 上。响应是线性的，一轮即收敛。
-%     实测数据见 README「纵向实测校验」。
 %======================================================================
 \begin{caloutside}
-\calskip{-4.330mm}                % 顶端补偿：原稿首行基线距版心顶 20.69pt
+\calskip{-4.330mm}                % 顶端补偿：首行基线距版心顶 20.69pt
 \calfontA\bfseries \calcno：\par
 \calskip{2.894mm}
 {\calfontA\bfseries \centering 中国海洋大学 \calcname 课程教学日历（理论课程）\par}
@@ -65,14 +64,14 @@
 %---- 课程信息：两行 ----
 % ⚠️ 原件这两段带 w:ind left="-540"(−9.525mm) firstLine="210"(+3.704mm)，
 %    相对原版心 31.75mm 的净起点 = 31.75 − 9.525 + 3.704 = 25.929mm
-%    = 73.48pt，与原稿实测 x=73.44pt 吻合。
+%    = 73.48pt，与实际x=73.44pt 吻合。
 %    caloutside 已把段落起点放回 31.75mm，故此处只需再左移 5.821mm。
 %
 % ⚠️ 两行之间用 \newline 而不是 \par —— 这是关键。
 %    原件的两行是 460 twips 固定行距、段距 0，基线相差 23.04pt。
 %    若用 \par 分成两段，**\baselineskip 不跨段落**，两段的间距变成
 %    「上段末行深度 + \parskip(0) + 下段首行高度」≈ 20.9pt，短 2.1pt，
-%    而且这个缺口**补不上**：实测 \vspace*{-2.11pt} 与 \calskip{-0.734mm}
+%    而且这个缺口**补不上**：实际\vspace*{-2.11pt} 与 \calskip{-0.734mm}
 %    都会被 TeX 在 \par 处丢弃（负的垂直胶不能压缩已有间距）。
 %    \newline 让两行落在同一段落里，\baselineskip = 23bp 直接生效。
 \calfontC
@@ -94,7 +93,7 @@
 %    \calweek{第X周} & \caldate{日期} & \calhourn{学时} & 教学内容 & 教学方式 & 课堂讨论/其它环节 & 课下作业/必读章节 \\
 %
 %  · 周次列前 10 行原件是左对齐、第 11 行起居中 —— 照抄原件这个不一致
-%    （见 README「原件的不一致之处」）。若想全列统一，把 \calctr 换 \calcell。
+%    （见 README「已知差异」）。若想全列统一，把 \calctr 换 \calcell。
 %  · 空格用 \\ 前的最后一个 & 结束；内容为空就留空。
 %======================================================================
 \begin{caltable}
@@ -108,9 +107,9 @@
 %    docGrid（linePitch=312 twips）排，行距 15.6pt，而其余 17 行都是
 %    23pt。**本模板不复制这个不一致**，全表统一 23pt。
 %
-%    后果：这一行比原稿高 22.2pt（69.5 → 46.5），总高多 22pt，表格
+%    后果：这一行比常规高 22.2pt（69.5 → 46.5），总高多 22pt，表格
 %    从 2 页变 3 页。这是有意取舍 —— 保真版式的同时不复制原件的疏漏，
-%    理由记在 README「原件的不一致之处」第 1 条。
+%    理由记在 README「已知差异」第 1 条。
 %    （若你确实要 2 页，把这一行改成 \calfall 系列宏、并把 sty 里
 %      row{2} 的 ht 改回 24.30pt。注意 \calfall 对 \par 分段无效，
 %      只对自动折行有效，改之前先读 sty §6 的说明。）
@@ -186,22 +185,22 @@
 %======================================================================
 % 【第 4 节】签字栏
 %
-%  原 .doc 的这两段（P008/P009）：
+%  的这两段（P008/P009）：
 %    「院（系）负责人签字：」  w:ind firstLine=4515 firstLineChars=2150
 %    「××××年  月  日」      无 ind，用空格顶到位置
 %
 %  firstLine = 4515 twips = 4515/1440×25.4 = 79.6396 mm
 %  ⇒ 相对原版心左边界 31.75mm，起点 = 31.75 + 79.6396 = 111.3896 mm = 315.75 pt
-%  原稿实测 x = 321.00pt —— 差 5.25pt，因为第一个字「院」的左边界
+%  实际x = 321.00pt —— 差 5.25pt，因为第一个字「院」的左边界
 %  与盒子起点之间还有字形的左边距（word 的 4515 是"首行缩进"，量的
-%  是盒子起点，不是字形起点）。故按实测 321.00pt 反解：
+%  是盒子起点，不是字形起点）。故按实际321.00pt 反解：
 %      缩进 = 321.00 − (31.75mm→89.999pt) = 231.00 pt = 81.49 mm
 %
 %  ⚠️ 两行的水平位置**不一样**：
 %      「院（系）」x=321.00   年份 x=352.50
 %    原件第二行是用空格顶的（不是缩进），照抄即可。
 %
-%  ⚠️ 第二行的三个锚点（逐字符实测原件 PDF，10.45pt 宋体）：
+%  ⚠️ 第二行的三个锚点（逐字符实际原件 PDF，10.45pt 宋体）：
 %      年字形 x = 355.08   月 x = 376.08   日 x = 397.08
 %      年→月 21.00pt，月→日 21.00pt（都是一个全角字 + 10.55pt 空档）
 %
@@ -213,7 +212,6 @@
 %    这样打出来的表格与学校原表逐字对齐，手写填空处一目了然。
 %
 %  ⚠️ 不要用负 \hspace 去挪：它只能压缩后续间距，减到负数就是重叠。
-%    （曾经为了塞进 \calgrade 占位符，用 \hspace{-8.35mm} 拽「月」，
 %     结果三个字叠成一个墨团。现已彻底去掉年份占位符，问题不存在了。）
 %======================================================================
 \begin{caloutside}