Skip to content

Instantly share code, notes, and snippets.

@zepinglee

zepinglee/latex2e-style-guide.md

Created December 18, 2021 13:06
Show Gist options
  • Save zepinglee/a4da5cab10b84348077eea45b6628f5c to your computer and use it in GitHub Desktop.
Save zepinglee/a4da5cab10b84348077eea45b6628f5c to your computer and use it in GitHub Desktop.
Download ZIP
LaTeX2e 编码风格指南
Raw
latex2e-style-guide.md

LaTeX2e 编码风格指南

本文提供的编码规范适用于使用 LaTeX2e 撰写的文档代码，主要目的是为了提升代码的可读性，减少可能的错误。 本指南不适用于 LaTeX2e 宏包（.sty）和文档类（.cls）以及 LaTeX3 的代码（应参考 “LaTeX3 style guide”）。

如果项目有自己的编码风格指南，优先使用该项目特定的指南。

代码布局

缩进

每级缩进使用 2 个空格。需要增加一级缩进的内容包括：

  • 使用 \begin 和 \end 开启和结束的环境。
  • 命令参数的大括号中。
  • 列表（itemize, enumerate 等）环境中 \item 转行后的文本。
  • 表格环境 tabular 中分割线（如 \toprule, \bottomrule）之间的内容。
  • \begingroup 和 \endgroup 命令之间。

比较特殊的是 begin{document} 和 \end{document} 之间的内容不缩进。 另外章节的标题命令（如 \chapter 和 \section）也不缩进。

% 推荐
\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}
% 不推荐
\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 列内。
  • 在每个句子结尾（句号、问号、叹号）换行。
  • 在每个句子结尾或者分句结尾（逗号，分号）换行。

在数学环境中，如果有较长的表达时需要换行，应在运算符前换行，同排版的习惯一致。

% 推荐
\begin{equation}
  c = a_1 + a_2 + \dots + a_n
      + b_1 + b_2 + \dots + b_b
\end{equation}
% 不推荐
\begin{equation}
  c = a_1 + a_2 + \dots + a_n +
      b_1 + b_2 + \dots + b_b
\end{equation}

空行

段落之间使用一个空行表示分段。

章节标题命令（如 \chapter, \section 等）后使用一个空行以凸显标题的位置。 标题命令与上一节段落之间使用 2 行以上的空行将不同章节分隔开。

% 推荐
上一节的内容。


\section{本节标题}

本节内容。
% 不推荐
上一节的内容。
\section{本节标题}
本节内容。

调用宏包

使用单独的一行导入宏包。这样更方便定位报错。

% 推荐
\usepackage{amsmath}
\usepackage{amssymb}
% 不推荐
\usepackage{amsmath, amssymb}

如果宏包提供了专有的配置命令，应优先使用，尽可能减少在调用宏包的可选参数重进行配置。

% 推荐
\usepackage{geometry}
\geometry{paper = a4paper, margin = 1in}
% 不推荐
\usepackage[paper=a4paper,margin=1in]{geometry}

有些宏包之间的调用顺序会影响配置的效果。 通常将所有宏包集中在一起调用，再进行相应的配置。 这是因为宏包在调用时会处理与其他宏包的兼容性，可能导致先前的配置失效。

比较特殊的是 hyperref 宏包应该在其他大多数的宏包载入和配置后再调用。 少数宏包会在其文档中注明需要在 hyperref 后调用。

% 推荐
\usepackage{geometry}
\usepackage{fancyhdr}
\usepackage{siunitx}

\geometry{...}
\fancypagestyle{plain}{...}
\sisetup{...}

\usepackage{hyperref}
\hypersetup{...}
% 不推荐
\usepackage{geometry}
\geometry{...}

\usepackage{hyperref}
\hypersetup{...}

\usepackage{fancyhdr}
\fancypagestyle{plain}{...}

\usepackage{siunitx}
\sisetup{...}

空格

行尾空格

避免在代码中行尾使用空格，一些编辑器在保存时会自动删掉行尾的空格。

在定义宏或者环境时，每行末尾应添加 % 以消除换行所引入的空格。 如果该行以宏结尾，则可以省略 %。 如果行尾的内容需要空格，应使用显式的 \space 命令。

% 推荐
\newcommand\printkeywords{%
  \small
  Keywords:\space
  \textbf{\keywords}%
}
% 不推荐
\newcommand\printkeywords{
  \small
  Keywords: %
  \textbftext{\keywords}
}

中西文之间的空格

本节内容假定使用 XeLaTeX 编译。

中文和西文（包括阿拉伯数字和数学符号）之间应手动加上空格。 这样有以下好处：

  • 虽然 xeCJK 在少数情况下无法自动处理中西文之间的空格，比如 图\ref{fig:1}中 和 color\color{blue}蓝。 在代码中统一手动添加空格可以避免这个问题。
  • 西文单词两侧有空格可以提升可读性。
% 推荐
函数 $f(x)$ 有 3 个间断点。
% 不推荐
函数$f(x)$有3个间断点。

在中西文之间添加 ~ 是 pdfTeX 和 cjk 宏包的用法，在 XeTeX 中会错误地禁止断行。

% 错误
函数~$f(x)$~有~3~个间断点。

数学环境

数学环境中的空格通常不影响排版的效果，但是可以提升代码的可读性。

相乘的字母之间使用空格。

% 推荐
e^{2 \pi i x \xi}
% 不推荐
e^{2\pi ix\xi}

运算符的两侧应添加空格。

% 推荐
S(n) = a_1 + a_2 + \dots + a_n
% 不推荐
S(n)=a_1+a_2+\dots+a_n

如果运算符有较高优先级，可以省略其两侧的空格。

% 推荐
c = (a+b) / (a-b)

逗号、冒号、分号后加空格。

% 推荐
a_1, a_2, a_3, \dots, a_n
% 不推荐
a_1,a_2,a_3,\dots,a_n

括号的内侧、函数名与括号之间通常不加空格。但如果括号有 \left, \big 等命令修饰，应在其两侧添加空格。

% 推荐
f(x) = \sin(\omega t + \phi)
f(x) = \sin \left( \omega t + \phi \right)
% 不推荐
f(x) = \sin ( \omega t + \phi )
f(x) = \sin\left(\omega t+\phi\right)

表格

表格环境 tabular 中 & 两侧、\\ 前应插入空格。 推荐使用编辑器插件（如 vim-align）将代码中表格的内容对齐。

% 推荐
\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}
% 可接受
\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}
% 不推荐
\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}

注释

代码修改时应优先更新注释，同代码相矛盾的注释比没有注释更糟糕。

注释块

注释块通常适用于紧随其后的代码，并且使用相同级别的缩进。 注释块的每行以一个百分号 % 和一个空格开始。

% 推荐
% 小四号
\zihao{-4}

\begin{center}
  % 斜体
  \itshape
\end{center}
%不推荐
\zihao{-4}
%小四号

\begin{center}
% 斜体
  \itshape
\end{center}

行内注释

行内注释就是注释和代码在同一行，它与代码之间至少用两个空格隔开。并且它以 % 和一个空格开始。 不要密集地使用行内注释。

% 推荐
\zihao{-4}  % 小四号
%不推荐
\zihao{-4}%小四号
\zihao{-4} %小四号
\zihao{-4} % 小四号

命名规范

在定义新的宏或环境时，应优先使用完整的英文单词或短语，尽可能避免使用缩写（除了众所周知的缩写）。

% 推荐
\newcommand\listoffiguresandtables{...}
\newcommand\articledoi{...}
% 不推荐
\newcommand\loft{...}

如果不方便使用英文表达，也可以使用汉语拼音，但在定义时应注释对应的词语。 注意不要使用拼音的首字母缩写。

% 推荐
% 字号
\newcommand\zihao[1]{...}
% 不推荐
\newcommand\zh[1]{...}

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment