文档结构：总结与挑战

摘要

本课结束本课程的第三单元，即文档结构单元。它重建从文档类通往自己的导言区的决定与机制之链，在每一环指出用到哪条原理、它在哪一课中确立；把已取得的成果放回课程计划中去衡量，并指明哪些只是略作预告的问题留给后面的单元；在结业测验中重复入门测验的各项技能；最后给出六道挑战题，难度高于各课的习题，要求综合几课的内容：根据规范规划一篇学位论文，预测一本书的编号和引用，以及诊断拆分成多个文件、编译失败或者说谎的文档。

学习目标

重建本单元各项决定与机制的先后次序，指出每一项所依据的原理。
解释编号、目录、交叉引用和部分编译如何依赖辅助文件。
区分本单元已经确立的内容和只作了预告、将由后续单元展开的内容。
诊断拆分成多个文件、编译失败或带着错误编号编译成功的文档，并排出修改的顺序。
根据一篇学位论文必须遵守的规范，规划它的文档类、页面、各部分、引用和文件。

本单元的收获

本单元的目标是：给文档一个架构，使它的编号、目录和引用在一切修改之后仍然真实。这个目标的达成，依靠的是导言宣布为前几个单元已知的内容：编译的多遍处理，导言区与正文的划分，以及逻辑标记。因此，走过的路可以读成由五段组成的一条链。

文档类与页面

讲文档类与页面的一课确立了：文档类决定有哪些分节层级、\maketitle 做什么、有没有摘要，以及偶数页与奇数页是否区分；由此推出按照结构和印刷方式在 article、report 和 book 之间选择的标准，并介绍了 KOMA-Script 的文档类，以及在这些例子所用的 TeX Live 版本中它们与西班牙语合用时所需的选项 es-noquoting。它逐一说明文档类的选项，解释页边距为什么取决于行长、如何用 geometry 设定，最后讲到页面样式，文档类的某些命令会自行强加页面样式。

章节、目录与附录

讲章节、目录与附录的一课排出了标题信息和摘要，整理了分节层级，并确立了两个彼此独立的计数器 secnumdepth 和 tocdepth 分别决定哪些标题编号、哪些标题进入目录。它说明目录是用上一遍记下的内容排出的，过时了也不发出警告；\appendix 改变其后内容的编号方式；书籍有三个部分，带两套页码，它们的顺序并非无关紧要。

交叉引用

讲交叉引用的一课确立了一切引用所依赖的原理：标签记录的是它之前、在它所在环境内最后分配的编号。由此推出标签在每种元素中应放在哪里，为什么放在图的标题之前的标签会指向节，以及为什么不编号的节没有可供引用的自己的编号。它说明修改之后只编译一遍，就会印出旧的编号，而且看上去完全正确；并介绍了必须在宏包最后加载的 hyperref，以及在它之后加载的 cleveref：在 \crefformat 或 \crefname 给出中文名称之前，cleveref 写的是英文名称。

长文档

讲长文档的一课把文档分成一个主文件和若干没有导言区的片段。它区分了 \input 和 \include：前者是逐字替换，后者另起一页、写出自己的辅助文件，并且支持 \includeonly，而后者的编号取决于此前一次完整编译留下的辅助文件。它确立了路径要从主文件所在的文件夹写起，在 Texmaker 中要设定主文档，并逐一分析了拆分文档特有的错误，其中有两种是无声的：\include 找不到的片段，以及带有导言区的片段，它的 \end{document} 会让整篇论文就此结束。

宏与自己的导言区

讲宏与自己的导言区的一课把逻辑标记变成了方法：带参数和带一个可选参数的 \newcommand，防止重新定义已被占用的名称的保护机制，无参数命令之后丢失的空格，\NewDocumentCommand，自定义环境（其参数只存在于开始部分），以及移入单独文件或宏包的导言区，它不应强加文档类、语言或 hyperref 的位置。

下图把五段汇成一条链。中间一列的每个节点是一项决定或一种机制，按彼此依赖的顺序编号，并用弧线连到它所用到的前面的环节；四周浮动的是支撑，即这条链一再求助的原理，每个支撑用实线连到依靠它的环节，用虚线连到确立它的环节，在前几个单元中确立的支撑则画成圆环。点击一个支撑，会突出显示所有用到它的环节；每个环节都链接到讲解它的那一课。

链的支柱

A多遍处理. 引擎在一遍处理中把编号、标题和页码记入辅助文件，在下一遍中使用它们。在第一单元中确立。本单元中不加证明而采用。
B导言区与正文. 导言区进行设置并加载宏包，正文负责排版；只做定义或保存的内容两处都可以放。在第一单元中确立。本单元中不加证明而采用。
C内容与形式. 作者声明每样东西是什么，在别处作出的决定确定它的样子。在前几个单元中确立。本单元中不加证明而采用。
D文档类说了算. 文档类决定有哪些分节层级、标题排出什么、有没有摘要、页面如何分配，以及它的命令强加哪种样式。确立于: 1. 三种标准文档类.
E标签记录什么. 标签记录它之前、在它所在环境内最后分配的编号，并不知道自己附着在什么东西上。确立于: 11. 标签与引用.
F加载顺序. 宏包按读入的顺序加载，后加载的宏包可能撤销先加载的宏包所做的事：hyperref 放在最后，cleveref 在它之后。确立于: 13. 链接.
G主文件. 编译的总是主文件；各片段是它正文的一部分，没有导言区，其路径从主文件所在的文件夹写起。确立于: 16. include 命令.

第 1 段文档类与页面
- 按文档的结构和印刷方式选择文档类。
- 声明文档类的选项并预测其效果。
- 用 geometry 设定页边距，而不使行长过长。
- 预测并更改页面样式、页眉和页脚。
1. 三种标准文档类. article 没有章；report 有章，标题和摘要各占单独的页面；book 双面印刷，没有摘要。
  依据: B (导言区与正文). 证明于: 文档类与页面.
2. KOMA-Script. scrartcl、scrreprt 和 scrbook 对应三种标准文档类，带有欧洲式的决定；与西班牙语的 babel 合用时，在这个版本中需要选项 es-noquoting。
  使用: 1. 三种标准文档类. 依据: C (内容与形式). 证明于: 文档类与页面.
3. 文档类选项. 纸张、字号、单面或双面、标题页、各章的起始页和草稿模式都在第一行声明。
  使用: 1. 三种标准文档类. 依据: D (文档类说了算). 证明于: 文档类与页面.
4. 页边距. geometry 根据少数几个尺寸算出页面；版心的宽度决定行长，而行长正是读者要承受的。
  使用: 3. 文档类选项. 依据: B (导言区与正文). 证明于: 文档类与页面.
5. 页面样式. 页面样式决定页眉和页脚；\maketitle 和 \chapter 给自己所在的页面强加 plain 样式，fancyhdr 或 scrlayer-scrpage 可以组合出自己的样式。
  使用: 1. 三种标准文档类, 4. 页边距. 依据: D (文档类说了算). 证明于: 文档类与页面.
第 2 段章节、目录与附录
- 按文档类排出标题和摘要。
- 选择分节层级，预测编号和目录。
- 生成目录和各种列表，知道它们依赖哪一遍。
- 安排附录和书籍的各个部分。
1. 标题与摘要. \title、\author 和 \date 负责保存，\maketitle 负责排版；abstract 环境存在于 article 和 report 中，book 中没有。
  使用: 1. 三种标准文档类. 依据: D (文档类说了算), B (导言区与正文). 证明于: 章节、目录与附录.
2. 分节层级. 七个层级，从部分到小段；章只存在于 report 和 book 中，层级不是按标题的字号来选的。
  使用: 1. 三种标准文档类. 依据: D (文档类说了算). 证明于: 章节、目录与附录.
3. 编号与目录. secnumdepth 决定哪些层级编号，tocdepth 决定哪些层级进入目录；带星号的形式既不编号，也不消耗编号。
  使用: 7. 分节层级. 依据: C (内容与形式). 证明于: 章节、目录与附录.
4. 目录与列表. 目录排出的是上一遍记入 .toc 文件的内容，过时了也不发出警告。
  使用: 7. 分节层级, 8. 编号与目录. 依据: A (多遍处理). 证明于: 章节、目录与附录.
5. 附录与书籍的各部分. \appendix 改变其后内容的编号方式；在 book 中，前置部分、正文部分和后置部分有两套页码，附录放在 \backmatter 之前。
  使用: 7. 分节层级, 5. 页面样式. 依据: D (文档类说了算). 证明于: 章节、目录与附录.
第 3 段交叉引用
- 放置标签并为其命名。
- 预见引用在一遍或两遍之后印出什么。
- 按顺序加载 hyperref 和 cleveref。
- 用名称和编号，或者用标题来引用。
1. 标签与引用. \label 标记一个位置，\ref 和 \pageref 写出它的编号和页码，需要两遍。
  使用: 7. 分节层级. 依据: A (多遍处理). 证明于: 交叉引用.
2. 标签放在哪里. 放在分配编号的命令之后，并在同一个环境之内：\section 之后，\caption 之后；加上说明其所指对象的前缀。
  使用: 11. 标签与引用. 依据: E (标签记录什么). 证明于: 交叉引用.
3. 链接. hyperref 把引用、目录和脚注变成链接，把节变成书签，并在宏包的最后加载。
  使用: 11. 标签与引用, 9. 目录与列表. 依据: B (导言区与正文). 证明于: 交叉引用.
4. 带名称的引用. cleveref 写出名称和编号；没有中文名称时它写英文名称（“section”），中文名称用 \crefformat 或 \crefname 设定；nameref 按标题引用。
  使用: 13. 链接, 12. 标签放在哪里. 依据: E (标签记录什么), F (加载顺序). 证明于: 交叉引用.
第 4 段长文档
- 为每个片段在 \input 和 \include 之间作出选择。
- 预测 \includeonly 保留了什么。
- 组织文件夹并设定主文档。
- 识别拆分文档中显性的和无声的错误。
1. input 命令. \input 插入一个文件，就像它的文字原本写在那里一样，既不分页，也不生成辅助文件。
  依据: B (导言区与正文). 证明于: 长文档.
2. include 命令. \include 在前后各另起一页，为每个片段写出自己的辅助文件，并且不能嵌套。
  使用: 15. input 命令, 7. 分节层级. 依据: A (多遍处理). 证明于: 长文档.
3. 部分编译. \includeonly 只排出选定的片段，其余片段则用它们的辅助文件来编号，这些辅助文件必须来自它们最后一次修改之后的完整编译。
  使用: 16. include 命令, 11. 标签与引用. 依据: A (多遍处理). 证明于: 长文档.
4. 文件夹与主文档. 主文件放在根目录，片段放在文件夹中，路径从主文件写起，名称简单，并在 Texmaker 中把主文件设为主文档。
  使用: 16. include 命令. 依据: G (主文件). 证明于: 长文档.
5. 拆分文档的错误. 找不到文件的 \input 会中止编译；找不到文件的 \include 只记下“No file”；带导言区的片段在它的 \end{document} 处结束整篇论文。
  使用: 16. include 命令, 18. 文件夹与主文档. 依据: G (主文件), B (导言区与正文). 证明于: 长文档.
第 5 段宏与自己的导言区
- 定义带参数和一个可选参数的命令。
- 区分定义、重新定义和提供定义，避免丢失空格。
- 定义自己的环境。
- 把导言区汇集到一个文件或一个宏包中。
1. 自定义命令. \newcommand 定义一个最多有九个参数的命令，第一个参数可以是带默认值的可选参数；它为一种反复出现的功能命名。
  依据: C (内容与形式). 证明于: 宏与自己的导言区.
2. 已占用的名称与空格. \newcommand 拒绝已经存在的名称，\renewcommand 拒绝不存在的名称；无参数的命令会吞掉其后的空格。
  使用: 20. 自定义命令. 依据: B (导言区与正文). 证明于: 宏与自己的导言区.
3. 自定义环境. \newenvironment 定义开始和结束部分；它的参数只存在于开始部分，\NewDocumentEnvironment 则允许在结束部分使用参数。
  使用: 20. 自定义命令. 依据: C (内容与形式). 证明于: 宏与自己的导言区.
4. 自己的导言区. 导言区可以移入用 \input 读入的文件，或移入 .sty 宏包；宏包不强加文档类、语言或 hyperref 的位置。
  使用: 20. 自定义命令, 21. 已占用的名称与空格, 15. input 命令, 13. 链接. 依据: F (加载顺序), C (内容与形式). 证明于: 宏与自己的导言区.

走向数学. 这条链停在架构已经完整、只待填充之处：编号的公式和定理将用本单元的标签来引用，它们是下一单元的内容。