refactor(xeCJK): 拆分超长 dtx 文件

[muzimuzhi]

另外，

1. ctex.dtx 这样上万行的大文件也建议拆开；

Originally posted by @zepinglee in #428

[github-actions]

📋 需求评审 #863

项目	结果
类型	工程改进 / 代码组织
涉及范围	ctex.dtx (13,163 行), xeCJK.dtx (15,117 行)
优先级	🟢 low（不影响用户功能）

📋 详细分析

现状：

仓库中两个超大 .dtx 文件：

• xeCJK/xeCJK.dtx — 15,117 行
• ctex/ctex.dtx — 13,163 行

其余 .dtx 文件均在 2,300 行以下，规模合理。

拆分的潜在收益：

• 降低单文件阅读和维护的认知负担
• 缩小 diff 范围，减少合并冲突
• 方便按功能模块独立审查

需要注意的问题：

• .dtx 格式的拆分不同于普通源代码——需要维护 \DocInput 顺序和 guard 标记的一致性
• l3build 的 unpack 流程依赖 .dtx 的 \generate 配置，拆分后需同步调整 build.lua
• 拆分方案需要设计：按功能模块（字体、heading、环境配置等）还是按引擎（通用/pdftex/xetex/luatex）划分
• LaTeX3 项目（如 l3kernel）已有成熟的多 .dtx 组织模式可参考

建议：标记为长期改进项，在下一个发版周期后择机实施。建议先处理 xeCJK.dtx（最大文件），积累经验后再处理 ctex.dtx。

[YDX-2147483647]

BIThesis 那边一月份也拆分了 dtx，想分享一下体验。由于我没看 #937 具体做法，就发到这边吧。

相关情况仅供参考，因为 BIThesis 那边更接近用户侧（主要分发*.cls），而且采用 doc strip 而不用 l3build。
另外拆分有「拆分文档手册与代码实现」和「拆分各个功能模块」两方面，而 BIThesis 当时只处理了后者（前者在历史上早就分开了）。

其实不太喜欢这种 ROI 低（俗称吃力不讨好）的工作。拆分的过程可能带来不少麻烦（比如排版的文档，能否正确 ref 之类的问题……），还不太容易用程序自动化排查。

原来拆分可以减少阅读代码时候的心智负担，但现在既然已经引入 AI，context 足够的时候这也不是问题了。so……
#937 (comment)

我大致同意以上结论（吃力不讨好），但具体情况和以上并不完全相同。

（➕ 偏积极，➖ 偏消极，0️⃣ 偏中性）

• 0️⃣ 拆分 dtx 可以保持生成的 cls 只有一份，并且保证 cls 在拆分前后只有开头注释The original source files were: …有变化。

• 追溯历史时，➕ 拆分后用 git log 很容易查看某一功能的全部历史，快速方便；但是 ➖ 追溯拆分文件那个 commit 之前的历史会变得很困难（拆分前后专门打两个 git tag 可缓解，不过效果有限）。

• 拆分会导致构建方式变化，➖ 从拆分前到拆分后 git bisect run 时，容易出现 untracked files，导致难以在 git bisect 中途做试验；不过 git bisect 的平均起点会随时间延后，所以过一段时间就很少有 git bisect 跨拆分了。

• 如果下游项目链接上游项目的代码，那么 ➕ 拆分上游项目 dtx 后，这个链接的行号会更稳定。

  比如下游中文字体如何才能与 Word 模板完全相同？（换用中易字库） | BIThesis 将上游ctex-fontset-windows.def中部分字体名改成了文件名，以适配 Overleaf 的沙箱环境。最初为了未来更新，留下了 ctex-kit 仓库中源代码的链接，其行号是 L11065-L11172，因为 ctex 未拆分 dtx 而特别大；但后来每年更新时，只看这个链接很难判断 ctex 原版ctex-fontset-windows.def是否有变化，所以事实上就没再检查更新过，全靠应届生试了之后被动接收反馈。如果 ctex 拆分 dtx，那么这个链接可以指向专门文件，方便下游检查更新，给应届生省时间。

• 长期项目拆分 dtx，与其说是纯按逻辑拆分功能模块，倒不如说是 0️⃣ 按编辑行为优化存储系统，把编辑频率相近或经常一起编辑的地方存到相同文件。

  BIThesis 有 thesis、report 等模板，thesis 经常改，而 report 很少改。拆分 dtx 前，人和AI修改 thesis 时都容易被 report 干扰，因为二者有很多名称、设计相近的地方；拆分 dtx 后，人改 thesis 就不用管 report 了，人看 AI 修改结果也很容易判断是否误改了 report。

  BIThesis 当时还把 thesis 拆分成了两个文件，一个是内部接口，另一个是面向用户的接口。现在发现这个拆分就不太理想，因为后者常常是前者简单包装，二者经常一起修改，拆分后反而容易漏改。

[myhsia]

BIThesis 那边一月份也拆分了 dtx，想分享一下体验。由于我没看 #937 具体做法，就发到这边吧。

相关情况仅供参考，因为 BIThesis 那边更接近用户侧（主要分发*.cls），而且采用 doc strip 而不用 l3build。 另外拆分有「拆分文档手册与代码实现」和「拆分各个功能模块」两方面，而 BIThesis 当时只处理了后者（前者在历史上早就分开了）。

目前的分区是: fontset 独自一个 dtx (后续有新字体那只需要贡献这个文件就好了, 虽然很长一段时间内估计不会有); 然后引擎的 def 拆出一个 (这个很底层了); 主要的 cls sty 拆出来一个 (ctex<art|book|rep|beamer>, ctex, ctexheading); 辅助甚至过时的 sty 拆出来一个 (比如 ctexcap ctexpatch 这种, 内部使用的); scheme 拆出来一个 (就是决定是否“翻译“, 是否执行 Chinese 本地化设置的); 以及手册 (包括 readme / .ins 文件) 独自一个.

综上, 「拆分文档手册与代码实现」和「拆分各个功能模块」 这个在 #937 中目前已基本满足.

• 如果下游项目链接上游项目的代码，那么 ➕ 拆分上游项目 dtx 后，这个链接的行号会更稳定。

比如下游中文字体如何才能与 Word 模板完全相同？（换用中易字库） | BIThesis 将上游ctex-fontset-windows.def中部分字体名改成了文件名，以适配 Overleaf 的沙箱环境。最初为了未来更新，留下了 ctex-kit 仓库中源代码的链接，其行号是 L11065-L11172，因为 ctex 未拆分 dtx 而特别大；但后来每年更新时，只看这个链接很难判断 ctex 原版ctex-fontset-windows.def是否有变化，所以事实上就没再检查更新过，全靠应届生试了之后被动接收反馈。如果 ctex 拆分 dtx，那么这个链接可以指向专门文件，方便下游检查更新，给应届生省时间。

@YDX-2147483647 是的! 很好的例子! 以后请指向 ctex-fontset.dtx! ~

[myhsia]

ctex.dtx 的拆分已在 #937 中完成, 对于 xeCJK.dtx, 考虑到如下问题

• 难以做到 ctex.dtx 那么功能分明: 如一部分处理字体, 一部分处理引擎, 一部分处理 headings, ...
• 如果尽可能考虑拆分, 则会出现以下问题
  • xeCJK 偏低层 wheel, 更改时经常会牵一发而动全身 —— 所有 .dtx 都要修改
  • 唯独可能考虑拆分出来的是 xeCJKfntef 包 以及文档自身, 但在不考虑 meta comment 的情况下, 经评估: xeCJKfntef ~ 11944-10523=1421 行, 文档自身 (包括 .ins, .md) ~ 1791-0=1791 行, 核心部分则剩余 15823-1421-1791=12611 行, 仍然保持 1e4 的数量级!
• 综上, xeCJK.dtx 拆分仅从代码行数方面带来的受益远不如 ctex.dtx.

考虑到 #511 提及对 xeCJK 重构, 所以即使真要拆分 xeCJK.dtx, 也会在重构时候考虑是否进行.
此 Issue 关闭, 并引用 #511.

[Liam0205]

@myhsia 重构可以。单纯的拆分，我旗帜鲜明地反对。