LaTeX 排版 00：学习路线与完整技术报告练习

以前的 LaTeX 笔记按“今天碰到什么命令”记录，查一个命令还可以，从头学习却容易失去方向。这次把原来的两篇文章重新编排：先理解源文件怎样变成文档，再学习公式与引用，最后处理图表和代码。每个主题都有解释、示例、常见错误和动手练习。

最终目标是一份能持续维护的中文技术报告：章节和编号自动更新，公式符号一致，图表可以在正文引用，文献有独立的数据文件，换一台电脑也能重新生成 PDF。全部文章集中在 LaTeX 排版分类。

一、先看完整路线

顺序	文章	核心问题	完成后的能力
00	本篇：学习路线与完整练习	学什么、怎样把各部分连起来	找到源文件、运行构建、检查结果
01	从最小文档到多文件工程	文档类、导言区、章节、页面、编译	从空文件写出中文报告，并定位第一个错误
02	数学公式、交叉引用与参考文献	数学语义、对齐、编号、文献流程	修改推导后自动更新引用和书目
03	图片、表格与代码清单	浮动体、尺寸、子图、数据表、程序	让图表在文档中清晰、稳定、便于比较

01 与 03 分别由 2019、2021 年的原文章重写，原来的链接仍然有效。旧文散落的图片、表格和代码配置集中到 03；公式和文献成为独立的 02。以后遇到问题，先判断属于哪一层，再到对应章节查找，避免重新积累一串互不关联的命令。

二、理解从源码到 PDF 的过程

LaTeX 文档与编译流程：正文和图片交给 XeLaTeX，文献交给 Biber，latexmk 调度到引用稳定后检查 PDF。

这个流程中有三种不同的输入：.tex 描述正文与结构，图片文件保存图形，.bib 保存文献信息。XeLaTeX 将它们纳入排版流程；Biber 处理文献数据；latexmk 根据依赖和日志决定需要重跑哪些步骤。

例如，在第一页插入一个新公式，会改变后面的公式编号。第一次编译把新编号写进辅助文件，后续编译再把引用更新到正文。目录、交叉引用和文献也是同样的思路。所以“运行过一次，没有报错”并不总意味着引用已经稳定。

这里统一选择 XeLaTeX + CTeX + latexmk + Biber。XeLaTeX 是引擎入口，CTeX 提供中文文档支持，latexmk 是构建调度工具，Biber 负责 BibLaTeX 的文献后端。若学校或期刊模板指定另一套工具链，应按模板要求调整。LaTeX 官方安装说明、CTeX、latexmk 和 BibLaTeX 分别说明了这些组件的职责。

三、下载一份完整工程

先对照成果，再修改源文件：

这份报告使用虚构的关节数据，演示文档结构、最小二乘公式、子图、三线表、跨行跨列、长表、代码与文献。数据仅用于练习排版。

latex_workshop/
├── main.tex                    # 文档类、宏包、标题与章节入口
├── sections/                   # 分主题正文
├── figures/
│   └── coordinate-frame.tex    # 可复现的 TikZ 图形源文件
├── references.bib              # 文献条目
└── README.md                   # 编译与练习说明

主文件负责全局配置；章节文件只写内容。编译时始终以主文件为入口。图片单独生成一次，修改图形后再重新生成。不要在每个章节中重复写 \documentclass 或 \begin{document}。

方式 A：使用仓库中的 Docker 环境

在网站仓库根目录执行：

./bin/site.sh latex-build
./bin/site.sh latex-test

第一次构建镜像需要下载 TeX 依赖；构建完成后，示例编译在无网络容器中运行。结果放在 build/latex-learning/ 下的新目录，包括 PDF、编译日志、提取出的正文、工具版本和逐页 PNG。原始练习文件以只读方式挂载，修改练习内容后重新运行即可。

想为某次练习留一个明确的名字，可以指定新的空输出目录：

./bin/site.sh latex-test build/latex-learning/my-first-report

检查分两层：脚本检查中文文本、交叉引用、文献和溢出警告；读者仍需要打开 PDF，检查分页、空白、图片尺寸和文字是否容易阅读。内容正确与视觉清晰需要分别确认。

方式 B：本机已经安装 TeX 发行版

解压源码，在含有 main.tex 的目录中执行：

xelatex -no-shell-escape -interaction=nonstopmode -halt-on-error \
  -output-directory=figures figures/coordinate-frame.tex
latexmk -xelatex -interaction=nonstopmode -halt-on-error main.tex

第一条生成插图 PDF，第二条生成报告 main.pdf。所需宏包见工程 README。引擎设置为 XeLaTeX，文献后端为 Biber；切换到在线编辑器时，也应保持这些设置，并准备好插图 PDF。不要只上传主文件而漏掉章节和文献。

四、分四次完成练习

第一次：写出文档骨架

改标题、作者和日期，新增“实验条件”小节，写一个有序列表和一个无序列表。再把这个小节移动到另一个位置。

验收：标题、目录、节编号和页码都由编译结果自动维护；能够解释正文与导言区的区别；知道应打开哪份日志。

第二次：把公式写成可以维护的推导

在最小二乘目标前新增一个编号公式；为它设置标签，在正文中引用。接着把两行各自编号的 align 改为共用一个编号的 equation + aligned，观察编号的变化。

验收：文中没有手写“公式 3”，没有未解析的 ??；等号对齐；向量与标量的字体约定一致；能说出二范数下标与平方上标的含义。

第三次：整理实验图和数据

改动坐标图的一个箭头，将表格加到五行，再给其中一项补一段较长的说明。复制长表的数据行，使它真正跨页，观察续页表头。

验收：图片保持宽高比；表格不超出版心；文字列自动换行；数值列按小数点对齐；长表能够跨页。解释 \linewidth 为什么会随 minipage 或子图改变。

第四次：补齐可交付的技术报告

添加一条自己真实阅读过的文献，并在正文引用。不要只把条目写进 .bib 后期待它自动出现在文献表中。最后把源码目录复制到一个新位置，从干净状态重新编译。

验收：文献作者、标题、年份准确；日志无未定义引用；源码、图片和书目完整；PDF 中没有缺字和遮挡；另一位读者能照 README 得到相同内容。

五、遇到问题时，先判断是哪一层

现象	优先检查	对应章节
提示找不到命令或宏包	引擎、发行版、包名、导言区	01：编译链与日志
中文缺字或字体不存在	是否用 XeLaTeX；字体配置是否依赖本机	01：中文最小文档
公式错位或出现数学模式错误	数学环境边界、括号、对齐符号	02：公式环境与排错
引用显示问号，文献为空	标签、引用键、Biber 日志、编译是否稳定	02：交叉引用与文献
图片找不到或位置出乎意料	相对路径、文件名大小写、浮动体规则	03：图片与浮动体
表格超出边界	列类型、宽度总和、单元格内容	03：数据表与长表
代码配色混乱	listings 配置键、语言、代码字符	03：代码清单

先看日志中的第一个实际错误，在最小文档中复现，再逐项恢复内容。一次增加很多宏包或替换整套模板，会让原因更难定位。

六、以后怎样扩展这套笔记

遇到一个新问题时，按“使用场景 → 最小示例 → 排版效果 → 原因 → 注意事项”的结构补到对应文章。宏包参数可以查手册，笔记应该保存的是选择它的理由、容易踩的坑，以及如何验证结果。

这一轮建立的是通用技术报告基础。学校论文格式、期刊模板和演示文稿有各自约束；需要时再以这套基础为前提单独增加专题，避免把不同模板的设置混进同一个导言区。