# latex2e-style-guide **Repository Path**: zepinglee/latex2e-style-guide ## Basic Information - **Project Name**: latex2e-style-guide - **Description**: LaTeX2e 编码风格指南 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 7 - **Forks**: 2 - **Created**: 2021-12-18 - **Last Updated**: 2023-02-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # LaTeX2e 编码风格指南 本文提供的编码规范适用于使用 LaTeX2e 撰写的文档代码，主要目的是为了提升代码的可读性，减少可能的错误。 本指南不适用于 LaTeX2e 宏包（`.sty`）和文档类（`.cls`）以及 LaTeX3 的代码（应参考 “[LaTeX3 style guide](http://mirrors.ctan.org/macros/latex/contrib/l3kernel/l3styleguide.pdf)”）。 如果项目有自己的编码风格指南，优先使用该项目特定的指南。 ## 代码布局 ### 缩进 每级缩进使用 2 个空格。需要增加一级缩进的内容包括： - 使用 `\begin` 和 `\end` 开启和结束的环境。 - 命令参数的大括号中。 - 列表（`itemize`, `enumerate` 等）环境中 `\item` 转行后的文本。 - 表格环境 `tabular` 中分割线（如 `\toprule`, `\bottomrule`）之间的内容。 - `\begingroup` 和 `\endgroup` 命令之间。 比较特殊的是 `begin{document}` 和 `\end{document}` 之间的内容不缩进。 另外章节的标题命令（如 `\chapter` 和 `\section`）也不缩进。 ```latex % 推荐 \title{% A long title% } \begin{itemize} \item First line of the item, Second line of the itme. \item First line of the item, Second line of the itme. \end{itemize} \begin{tabular}{lll} \toprule Option name & Type & Default \\ \midrule color & Literal & \meta{none} \\ mode & Choice & math \\ number-color & Literal & \meta{none} \\ number-mode & Choice & math \\ propagate-math-font & Switch & false \\ \bottomrule \end{tabular} ``` ```latex % 不推荐 \title{% A long title% } \begin{itemize} \item First line of the item, Second line of the itme. \item First line of the item, Second line of the itme. \end{itemize} \begin{tabular}{lll} \toprule Option name & Type & Default \\ \midrule color & Literal & \meta{none} \\ mode & Choice & math \\ number-color & Literal & \meta{none} \\ number-mode & Choice & math \\ propagate-math-font & Switch & false \\ \bottomrule \end{tabular} ``` ### 换行 以下换行方式均可接受。 - 保持每行在 80 或 120 列内。 - 在每个句子结尾（句号、问号、叹号）换行。 - 在每个句子结尾或者分句结尾（逗号，分号）换行。 在数学环境中，如果有较长的表达时需要换行，应在运算符前换行，同排版的习惯一致。 ```latex % 推荐 \begin{equation} c = a_1 + a_2 + \dots + a_n + b_1 + b_2 + \dots + b_b \end{equation} ``` ```latex % 不推荐 \begin{equation} c = a_1 + a_2 + \dots + a_n + b_1 + b_2 + \dots + b_b \end{equation} ``` ### 空行 段落之间使用一个空行表示分段。 章节标题命令（如 `\chapter`, `\section` 等）后使用一个空行以凸显标题的位置。 标题命令与上一节段落之间使用 2 行以上的空行将不同章节分隔开。 ```latex % 推荐 上一节的内容。 \section{本节标题} 本节内容。 ``` ```latex % 不推荐 上一节的内容。 \section{本节标题} 本节内容。 ``` ### 调用宏包 使用单独的一行导入宏包。这样更方便定位报错。 ```latex % 推荐 \usepackage{amsmath} \usepackage{amssymb} ``` ```latex % 不推荐 \usepackage{amsmath, amssymb} ``` 如果宏包提供了专有的配置命令，应优先使用，尽可能减少在调用宏包的可选参数重进行配置。 ```latex % 推荐 \usepackage{geometry} \geometry{paper = a4paper, margin = 1in} ``` ```latex % 不推荐 \usepackage[paper=a4paper,margin=1in]{geometry} ``` 有些宏包之间的调用顺序会影响配置的效果。 通常将所有宏包集中在一起调用，再进行相应的配置。 这是因为宏包在调用时会处理与其他宏包的兼容性，可能导致先前的配置失效。 比较特殊的是 `hyperref` 宏包应该在其他大多数的宏包载入和配置后再调用。 少数宏包会在其文档中注明需要在 `hyperref` 后调用。 ```latex % 推荐 \usepackage{geometry} \usepackage{fancyhdr} \usepackage{siunitx} \geometry{...} \fancypagestyle{plain}{...} \sisetup{...} \usepackage{hyperref} \hypersetup{...} ``` ```latex % 不推荐 \usepackage{geometry} \geometry{...} \usepackage{hyperref} \hypersetup{...} \usepackage{fancyhdr} \fancypagestyle{plain}{...} \usepackage{siunitx} \sisetup{...} ``` ## 空格 ### 行尾空格 避免在代码中行尾使用空格，一些编辑器在保存时会自动删掉行尾的空格。 在定义宏或者环境时，每行末尾应添加 `%` 以消除换行所引入的空格。 如果该行以宏结尾，则可以省略 `%`。 如果行尾的内容需要空格，应使用显式的 `\space` 命令。 ```latex % 推荐 \newcommand\printkeywords{% \small Keywords:\space \textbf{\keywords}% } ``` ```latex % 不推荐 \newcommand\printkeywords{ \small Keywords: % \textbftext{\keywords} } ``` ### 中西文之间的空格 本节内容假定使用 XeLaTeX 编译。 中文和西文（包括阿拉伯数字和数学符号）之间应手动加上空格。 这样有以下好处： - 虽然 xeCJK 在少数情况下无法自动处理中西文之间的空格，比如 `图\ref{fig:1}中` 和 `color\color{blue}蓝`。 在代码中统一手动添加空格可以避免这个问题。 - 西文单词两侧有空格可以提升可读性。 ```latex % 推荐 函数 $f(x)$ 有 3 个间断点。 ``` ```latex % 不推荐 函数$f(x)$有3个间断点。 ``` 在中西文之间添加 `~` 是 pdfTeX 和 `cjk` 宏包的用法，在 XeTeX 中会错误地禁止断行。 ```latex % 错误 函数~$f(x)$~有~3~个间断点。 ``` ### 数学环境 数学环境中的空格通常不影响排版的效果，但是可以提升代码的可读性。 相乘的字母之间使用空格。 ```latex % 推荐 e^{2 \pi i x \xi} ``` ```latex % 不推荐 e^{2\pi ix\xi} ``` 运算符的两侧应添加空格。 ```latex % 推荐 S(n) = a_1 + a_2 + \dots + a_n ``` ```latex % 不推荐 S(n)=a_1+a_2+\dots+a_n ``` 如果运算符有较高优先级，可以省略其两侧的空格。 ```latex % 推荐 c = (a+b) / (a-b) ``` 逗号、冒号、分号后加空格。 ```latex % 推荐 a_1, a_2, a_3, \dots, a_n ``` ```latex % 不推荐 a_1,a_2,a_3,\dots,a_n ``` 括号的内侧、函数名与括号之间通常不加空格。但如果括号有 `\left`, `\big` 等命令修饰，应在其两侧添加空格。 ```latex % 推荐 f(x) = \sin(\omega t + \phi) f(x) = \sin \left( \omega t + \phi \right) ``` ```latex % 不推荐 f(x) = \sin ( \omega t + \phi ) f(x) = \sin\left(\omega t+\phi\right) ``` ### 表格 表格环境 `tabular` 中 `&` 两侧、`\\` 前应插入空格。 推荐使用编辑器插件（如 `vim-align`）将代码中表格的内容对齐。 ```latex % 推荐 \begin{tabular}{lll} color & Literal & \meta{none} \\ mode & Choice & math \\ number-color & Literal & \meta{none} \\ number-mode & Choice & math \\ propagate-math-font & Switch & false \\ \end{tabular} ``` ```latex % 可接受 \begin{tabular}{lll} color & Literal & \meta{none} \\ mode & Choice & math \\ number-color & Literal & \meta{none} \\ number-mode & Choice & math \\ propagate-math-font & Switch & false \\ \end{tabular} ``` ```latex % 不推荐 \begin{tabular}{lll} color&Literal&\meta{none}\\ mode&Choice&math\\ number-color&Literal&\meta{none}\\ number-mode&Choice&math\\ propagate-math-font&Switch&false\\ \end{tabular} ``` ## 注释 代码修改时应优先更新注释，同代码相矛盾的注释比没有注释更糟糕。 ### 注释块 注释块通常适用于紧随其后的代码，并且使用相同级别的缩进。 注释块的每行以一个百分号 `%` 和一个空格开始。 ```latex % 推荐 % 小四号 \zihao{-4} \begin{center} % 斜体 \itshape \end{center} ``` ```latex %不推荐 \zihao{-4} %小四号 \begin{center} % 斜体 \itshape \end{center} ``` ### 行内注释 行内注释就是注释和代码在同一行，它与代码之间至少用两个空格隔开。并且它以 `%` 和一个空格开始。 不要密集地使用行内注释。 ```latex % 推荐 \zihao{-4} % 小四号 ``` ```latex %不推荐 \zihao{-4}%小四号 \zihao{-4} %小四号 \zihao{-4} % 小四号 ``` ## 命名规范 在定义新的宏或环境时，应优先使用完整的英文单词或短语，尽可能避免使用缩写（除了众所周知的缩写）。 ```latex % 推荐 \newcommand\listoffiguresandtables{...} \newcommand\articledoi{...} ``` ```latex % 不推荐 \newcommand\loft{...} ``` 如果不方便使用英文表达，也可以使用汉语拼音，但在定义时应注释对应的词语。 注意不要使用拼音的首字母缩写。 ```latex % 推荐 % 字号 \newcommand\zihao[1]{...} ``` ```latex % 不推荐 \newcommand\zh[1]{...} ``` ## References - Didier Verna. [Towards LaTeX coding standards](https://tug.org/TUGboat/tb32-3/tb102verna.pdf). TUGboar, 2011, 32(3). .