LaTeX 模板开发最佳实践

原则

内容与格式分离：文档中的标记应表达语义，控制具体的格式的代码应集中放在 cls 文件中。
最小化：模板的主要目的，是为常见文档组件提供一套定制的样式。不要期待模板面面俱到，不常见的文档组件（例如伪代码排版）应由用户通过调用宏包自行实现。可参考 IEEEtran 的做法。

尽量通过调用常见的宏包调用来实现样式定制。
- 常见的宏包经过广泛的使用和反复修改，可以避免很多宏包之间的冲突。
了解所用宏包的依赖项，了解特定宏包组合的加载顺序要求。
不在模板和示例文档中，重复加载同一个宏包或同一个宏包的组件（例如 tikz library, minted library）。
集中加载宏包组件，不在模板中零散加载。
控制宏包使用数量（最小化原则）。
1. 仅少数用户需要的、宏包加载后配置简单的功能，可考虑不依赖相关宏包。需要时用户自行加载即可。例如排版算法/伪代码、浮动体双语标题、页面水印等功能。如果要在用户调用某宏包后自动进行配置，可以使用 filehook 或 ctexhook。
2. 功能重合度较高的宏包，若非必要，不同时使用。例如控制章节标题样式的宏包 ctexheading 和 titlesec，提供 if-else 功能的宏包 ifthen 和 etoolbox 等。

尽量避免手动重定义基础命令，例如 \chapter、\l@section。
尽量避免定义新命令以「抽象」基础命令，例如 \newcommand\myChapter[1]{\chapter{附录：#1}}。新命令会增加用户的使用门槛；到社区寻求帮助，「抽象」基础命令的需求通常都有更好的实现方式。
尽量使用 latex2e 风格的命令，如 counter 相关的、length 相关的、h/vspace 相关的。若非必要，不使用 tex 风格的命令和赋值方式。若非必要，不混用两种风格的命令，如一会儿 \hspace 一会儿 \hskip
了解空格的各种产生方式，注释源码中的多余空格
不滥用 \nobreakspace，即 ~
区分带参数与不带参数的命令，区分改变状态与制造输出的命令。
- 反例：
- 在不带参数的命令后，使用（额外的、不起任何作用的）大括号，例如 \songti{}（出处）
- 把不带参数的命令，当成带参数的命令来使用，例如 \small{text in small size}（出处）
了解作用域、分组（grouping）和 \global
- 建议使用 \begingroup ... 多行内容 ... \endgroup 制造长分组，使用 {...} 制造短分组。
- 知道 latex 环境自带分组，避免在使用时额外添加分组
- 防止命令作用域「溢出」，反例：
- cctart.cls 中在 \figurename 里直接使用 \bf，见一处源码和讨论文章

如果有大段复制粘贴的代码，建议以注释形式说明来源，方便后续维护。
使用缩进。保持缩进风格统一，不将空格和 Tab 混用。建议每层缩进使用 2 个或 4 个空格，其中 2 个空格是 latex3 推荐使用的（ texdoc l3styleguide）

除非必要，不使用 LaTeX 2.09 风格的字体切换命令，例如 \rm, \bf 等
在切换字体之前，推荐使用 \normalfont 把字体恢复到 \rmfamily。类似的命令还有 \normalsize
谨慎使用 \songti、\heiti 等只作用于 CJK 文字的命令，它们不会修改西文字体。推荐使用 \rmfamily, \sffamily 等命令，使西文与中文字体的风格保持一致。
在了解它们的初始定义之前，不要直接修改 \large, \small 等命令的定义
修改行距：推荐使用 setspace/zhlineskip 宏包和 \linespread，可以接受修改 \baselinestretch，一定不要直接修改 \baselineskip
\linespread{...} 和 \fontsize{...}{...} 后面一定要跟 \selectfont
控制示例文档中字体和字号切换命令的使用频次。它们应该隐藏在模板内部，不应该被模板用户（频繁）直接使用。

模板应提供用户文档。用户文档的形式自由，推荐包含以下内容

问题的反馈方式，包括但不限于维护者的联系方式、模板的在线托管地址等。
建议推荐几个问答社区，方便用户寻求解答。
模板适用的操作系统和编译方式。
1. 如果编译时需要使用选项 -shell-escape，应特别说明
2. 如果提供了操作系统相关的辅助编译工具，如 Makefile，应特别说明
3. 对写在 tex 文件开头的 magic comment，不同编辑器的支持情况不同，不建议仅通过 magic comment 指定编译方式和选项。建议在用户文档中明确说明。
模板定义的新命令的用法，模板修改过的既有命令的新用法或新效果
使用模板应遵循的文件结构，通常包括子文件的默认路径、图片和其他文件的默认路径等
文件结构可以在用户文档里通过文字说明，也可以在（随模板一起分发的）示例文档里通过实践体现
如果使用了 CTAN 未收录的功能性宏包，建议提供获取方式，并在文档中特别说明。可选将这类依赖随模板一起分发
如果使用了操作系统不预装的字体，建议单独说明。如果该字体是免费可获取的，建议列出获取方式，并提示授权使用范围。
- Windows 10 预装字体，macOS 各版本预装字体

包含完整的模板源码和用户文档的文件或文件包，即是一份模板的发布。如果模板需要长期维护（功能和文档的增删改），模板应该使用版本号、更新日志来记录变化，同时考虑使用版本管理软件，例如 Git。

用 Git 管理 LaTeX 项目时，以下问题值得关注

管理哪些文件
- LaTeX 辅助文件，不管理。推荐这个适用于 LaTeX 项目的 .gitignore 模板
- 二进制文件，可以管理，控制更新频次（以控制模板项目的大小）
  - 图片文件，尽可能使用 mwe 宏包提供的示例图片
  - PDF 文件，例如用户文档或示例文档，只在发布新版时更新。如果在 GitHub 托管，可以考虑只管理生成 PDF 的源码，通过 Release 功能提供编译得到的文档。
每次提交，commit message 要言之有物。
反例：wangxianyu7/sdu_wh_latex/commits, mohuangrui/ucasthesis/commits