summaryrefslogtreecommitdiff
path: root/info/lshort/chinese/src/chap/app.B.error.help.tex
blob: fb14d48bb34286d7121d006b46b0cc2be5c5ec57 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
\chapter{排除错误、寻求帮助}\label{chap:error-helps}

\begin{intro}
\LaTeX{} 入门用户总会为两大问题头疼:我写的代码到底哪里出错了?如果想要实现某种用法该怎么办?
本章首先总结了常见的 \LaTeX{} 错误及应对的办法。
\end{intro}

\section{\LaTeX{} 错误}\label{sec:errors}

当我们用排版引擎编译 \LaTeX{} 代码时,命令行的窗口(终端)会显示大量信息(TeXworks 等编辑器会有一个区域显示这些信息)。
当编译过程中出现错误时,信息将会停止在出错的地方,等待我们接下来的操作。

比如说我们有一个明显出错的例子:
\begin{verbatim}
\documentclass{article}
\begin{document}
Test \LaTEx{} and it's friends.
\end{document}
\end{verbatim}

编译过程中遇到这个错误将会停顿下来,提示错误,并等待用户输入指令:
\begin{verbatim}
! Undefined control sequence.
l.3 Test \LaTEx
             {} and it's friends.
\end{verbatim}

这种错误信息分两部分,前一部分提示了错误的信息,后一部分指出了错误发生的行号,
以及通过错落的文字告知发生错误的命令所在位置。如上错误显示 \cmd{LaTEx} 位置发生了错误,错误信息是“未定义的控制序列”,
意思是 \cmd{LaTEx} 是 \TeX{} 编译器无法识别的一个命令,很显然是我们把 \cmd{LaTeX} 的大小写写错了。

\subsubsection{处理方式}

出现错误时,编译过程将暂停,等待用户输入命令。用户可以直接敲回车跳过当前的错误,继续编译,相当于丢掉了写错的命令,
将``Test and it's friends.''排版出来。但这个例子过于简单,有些复杂的代码中,有可能会由于一个小问题导致一连串的错误。
此时可以选择按 \textbf{S/R/Q} 选择跳过接下来的所有错误,或者按 \textbf{X} 直接退出编译,将源代码中的错误修改后重新编译。

\subsubsection{常见的 \LaTeX{} 错误信息}

笔者在此总结一些经常发生、问题比较明确的 \LaTeX{} 错误:

\long\def\LaTeXerror#1{\begingroup\color{red}\bfseries\ttfamily{}#1\endgroup}

\begin{itemize}
\item \LaTeXerror{! Undefined control sequences.}

使用了未定义的命令。拼写错误是原因之一,如把 \cmd{LaTeX} 写作 \cmd{Latex} 这样。
也有可能是没有调用某个宏包,但用了该宏包定义的命令。

\item \LaTeXerror{!  LaTeX error: Environment ... undefined.}

使用了未定义的环境。

\item \LaTeXerror{! Missing \$ inserted.}

缺少数学环境的符号 \texttt\$。多由于将数学符号用在公式之外而导致。

\item \LaTeXerror{Runaway argument? \\
                  ! Paragraph ended before ... was complete.}

\item \LaTeXerror{! File ended while scanning definition/use of ...}

这两个错误主要是由于漏写了包裹命令参数的花括号,导致识别参数时出现错误。许多编辑器的括号配对功能有助于检查和消除这类错误。

这类错误还有可能是由于前一次编译中断导致 \texttt{.aux} 等辅助文件不完整,再次编译读入不完整的文件产生错误。解决办法是删除辅助文件并重新编译。

\item \LaTeXerror{! Extra alignment tab has been changed to \cmd{cr}.}

\item \LaTeXerror{! Misplaced \cmd{noalign}.}

两个错误信息都与表格有关。
\begin{itemize}
  \item 前者的字面意义是“一行中使用的列分隔符 \texttt\& 太多”,有时可能确实是 \texttt\& 的个数和列格式不匹配,
  但多数情况是漏掉了行尾的 \crcmd{} 命令。
  \item 后者常出现于漏掉了行尾的 \crcmd{} 命令而接着使用 \cmd{hline} 命令画横线的时候。
\end{itemize}

\item \LaTeXerror{!  LaTeX Error: Lonely \cmd{item}-{}-perhaps a missing list environment.}

\item \LaTeXerror{!  LaTeX Error: Something's wrong-{}-perhaps a missing \cmd{item}.}

两个错误信息都与列表环境和 \cmd{item} 命令有关。前者意味着在没有使用列表环境的情况下用了 \cmd{item};
后者则相反,是在列表环境中漏了 \cmd{item}。

\item \LaTeXerror{! I can't find file `...'.}

\item \LaTeXerror{!  LaTeX Error: File `...' not found.}

两个错误都意味着缺少文件。
\begin{itemize}
  \item 如果使用 \cmd{input} 或者 \cmd{include} 命令添加文件,出现上述错误的原因当然是文件不存在或者文件名不对;
  \item 如果错误提示里的文件名带 \texttt{.cls} 或者 \texttt{.sty} 扩展名,那么很显然,是因为\textbf{没有安装所需的宏包或文档类}。
\end{itemize}

\item \LaTeXerror{!  LaTeX Error: Missing \cmd{begin}\marg*{document}.}

字面上是缺少 \cmd{begin}\marg*{docu\-ment},实际上往往是由于在 \cmd{begin}\marg*{docu\-ment} 之前(导言区)输入了文字或某些命令。

\item \LaTeXerror{!  LaTeX Error: Can be used only in preamble.}

与上一条相反,由于将必须用于导言区的命令在 \cmd{begin}\marg*{docu\-ment} 之后使用而产生。

\item \LaTeXerror{!  LaTeX Error: \cmd{begin}\marg*{...} on input line ... ended by \cmd{end}\marg*{...}.}

环境首尾不匹配。比如 \cmd{begin}\marg*{enumerate} 用了 \cmd{end}\marg*{itemize} 结尾。或者也可能是由于漏写了 \cmd{begin}
或者 \cmd{end} 命令。

\item \LaTeXerror{!  LaTeX Error: Option clash for package `...'.}

以\textbf{不同选项}重复调用宏包造成冲突。有可能是因为其它宏包内部事先调用了这个宏包,用户再次带选项调用而导致冲突。
解决问题的办法是去掉重复调用的宏包。如果宏包允许的话,尽量使用其定义的命令改变设置,减少宏包选项的使用。

\item \LaTeXerror{!  LaTeX Error: Command ... already defined, \\
                     or name \cmd{end}... illegal ...}

使用 \cmd{newcommand} 或 \cmd{newenvironment} 定义已有的命令/环境时产生的错误。如果自己确实作了定义,可考虑用
\cmd{re\-new\-command} 或 \cmd{re\-new\-environment} 定义;如果是宏包定义的命令产生了这个错误,则属于隐性的宏包冲突。

相比之前的 ``Option Clash''{},隐性宏包冲突是更难以解决的问题,对各种宏包不熟悉的用户,尤其是使用模板的用户而言,往往难以下手。
用户可尝试查找引起冲突的宏包的帮助文档。详尽的手册里通常会告知用户这个宏包应当在某个宏包的前面/后面调用,或者不能与某个宏包一起调用。
如果是模板调用了大量宏包导致冲突,可联系模板的作者解决。

\item \LaTeXerror{!  LaTeX Error: Unknown option `...' for package `...'.}

调用宏包时指定了不能被其识别的选项。此时应该查找宏包的帮助文档来解决问题。

\item \LaTeXerror{!  Package `...' error: ...}

宏包或文档类自定义的错误,由于不正确地使用宏包里的命令而导致。此时应该查找宏包的帮助文档来解决问题。

\end{itemize}

\section{查找帮助文档}\label{sec:texdoc}

\index{texdoc@\texttt{texdoc} 工具}
无论是 \hologo{TeXLive} 还是 \hologo{MiKTeX},提供了一个命令行模式的程序 \texttt{texdoc}。
比如对 \ref{subsec:fancyhdr} 小节的 \pkg{fancyhdr} 宏包感兴趣,这时在 Windows 命令提示符或者 Linux 终端输入以下命令,
则会弹出宏包的帮助文档 \texttt{fancyhdr.pdf}:
\begin{verbatim}
texdoc fancyhdr
\end{verbatim}

除了宏包的帮助文档外,\TeX{} 发行版还包括了各类有用的文档,有一部分在参考文献中给出。

如果不熟悉命令行工具的话,\hologo{TeXLive} 提供了一个图形界面的程序 TeXdoc GUI。打开后,可以看到程序里的许多按钮,分别代表某一类的帮助文档。
除此之外,点击 File Search 弹出搜索框,输入想要搜索的宏包和文件并按回车键,TeXdoc GUI 会弹出它搜索到的所有结果,可点击任意一项来打开文档。

当然对于初学者,有一个现实而棘手的问题:\textbf{某个命令到底是 \LaTeX{} 自有的,还是哪个宏包提供的?}
很遗憾地说,除了通过慢慢积累、熟悉较多宏包之外,没有很方便的办法解决这个问题,因为 \LaTeX{} 的宏包实在太丰富了。
本手册末尾的索引给出了所有在本手册见到的命令和环境,其中哪些命令和环境需要调用哪个宏包才能使用,一目了然。但是这个索引远远不够。

解决这个问题有几点可行的办法:
\begin{enumerate}
  \item 查询一些综述性的资料,如总结所有 \LaTeX{} 自带命令的文档 \cite{latex2e}、\LaTeX{} 符号大全 \cite{symbols} 等;
  \item 在互联网上搜索自己不清楚的命令;
  \item 在论坛上提问求助有经验的人。
\end{enumerate}

\section{常用宏包简介}\label{sec:pkg-list}

\def\pkglabel#1{\makebox[60pt][l]{\pkg{#1}}}
\newenvironment{pkglist}%
  {\list{}{%
    \labelwidth=60pt
    \itemindent=0pt
    \leftmargin=60pt
    \labelsep=0pt
    \let\makelabel\pkglabel}}%
  {\endlist}

此处不包含设置字体或数学符号的宏包,它们已经在表 \ref{tbl:font-pkgs} 中列出。

\subsection{文字、公式和符号}\label{subsec:text-math-symbols}

\begin{pkglist}
  \item[amsmath]  \hologo{AmS} 数学公式扩展。
  \item[mathtools] 数学公式扩展宏包,提供了公式编号定制和更多的符号、矩阵等。
  \item[amsfonts] \hologo{AmS} 扩展符号的基础字体支持。
  \item[amssymb]  在 \pkg{amsfonts} 基础上将 \hologo{AmS} 扩展符号定义成命令。
  \item[bm]       提供将数学符号加粗的命令 \cmd{bm}。
  \item[siunitx]  以国际单位规范排版物理量的单位。
  \item[mhchem]   排版化学式和方程式。
  \item[tipa]     排版国际音标。
\end{pkglist}

\subsection{排版元素}\label{subsec:pkg-elements}

\begin{pkglist}
  \item[ulem]     提供排版可断行下划线的命令 \cmd{uline} 以及其它装饰文字的命令。
  \item[endnote]  排版尾注。
  \item[marginnote] 改善的边注排版功能。
  \item[multicol] 提供将内容自由分栏的 \env{multicols} 环境。
  \item[multitoc] 生成多栏排版的目录。
  \item[minitoc]  为章节生成独立的小目录。
  \item[glossaries] 生成词汇表。
  \item[verbatim] 对原始的 \env{verbatim} 环境的改善。提供了命令 \cmd{verbatim\-input} 调用源文件。
  \item[fancyvrb] 提供了代码排版环境 \env{Verbatim} 以及对版式的自定义。
  \item[listings] 提供了排版关键字高亮的代码环境 \env{lst\-listing} 以及对版式的自定义。类似宏包有 \pkg{minted}。
  \item[algorithmic] 一个简单的实现算法排版的宏包。如果要生成浮动体的话,需要搭配 \pkg{algorithm} 宏包使用。
  \item[algorithm2e] 较为复杂的、可定制的算法排版宏包。类似宏包有 \pkg{algorithmicx} 等。
  \item[ntheorem] 定制定理环境。类似宏包包括 \pkg{theorem}、\pkg{thmtools}、\pkg{amsthm} 等。
  \item[mdframed] 排版可自动断页的带边框文字段落,提供边框样式的定制功能。
  \item[tcolorbox] 以 \hologo{TikZ} 为基础提供排版样式丰富的彩色盒子的功能。
\end{pkglist}

\subsection{图表和浮动体}\label{subsec:pkg-tab-fig}

\begin{pkglist}
  \item[booktabs]  排版三线表。
  \item[array]    对表格列格式的扩展。
  \item[tabularx] 提供 \env{tabularx} 环境排版定宽表格,支持自动计算宽度的 X 列格式。
  \item[arydshln] 支持排版虚线表格线。
  \item[colortbl] 支持修改表格的行、列、单元格的颜色。
  \item[multirow] 支持合并多行单元格。
  \item[makecell] 支持在单元格里排版多行内容(嵌套一个单列的小表格)。
  \item[diagbox]  排版斜线表头。
  \item[longtable] 提供排版跨页长表格的 \env{longtable} 环境。
  \item[ltxtable] 跨页长表格可使用 \env{tabularx} 的 X 列格式。
  \item[tabu]     提供排版复杂格式表格的 \env{tabu} 环境。与 \pkg{longtable} 一同调用时,提供排版复杂格式跨页长表格的 \env{longtabu} 环境。
  \item[graphicx] 支持插图。
  \item[bmpsize]  \texttt{latex} + \texttt{dvipdfmx} 命令下支持 BMP/JPG/PNG 等格式的位图。
  \item[epstopdf] \texttt{pdflatex} 命令下支持 EPS 格式的矢量图。
  \item[wrapfig]  支持简单的文字在图片周围的绕排。
  \item[subfig]   提供子图表和子标题的排版。类似宏包有 \pkg{subfigure} 和 \pkg{subcaption} 等。
  \item[caption]  控制浮动体标题的格式。
  \item[bicaption] 生成双语浮动体标题。
  \item[float]    为浮动体提供不浮动的 H 模式;提供自定义浮动体结构的功能。
\end{pkglist}

\subsection{修改版式}\label{subsec:pkg-layout}

\begin{pkglist}
  \item[geometry] 修改页面尺寸、页边距、页眉页脚等参数。
  \item[fancyhdr] 修改页眉页脚格式,令页眉页脚可以左对齐、居中、右对齐。
  \item[titlesec] 修改章节标题 \cmd{chapter}、\cmd{section} 等的格式。
  \item[titletoc] 修改目录中各条目的格式。
  \item[tocloft]  类似 \pkg{titletoc} 的修改目录条目格式的宏包。
  \item[tocbibind] 支持将目录、参考文献、索引本身写入目录项。
  \item[footmisc] 修改脚注 \cmd{footnote} 的格式。
  \item[indentfirst] 令章节标题后的第一段首行缩进。
  \item[enumerate] 提供简单的自定义标签格式的 \env{enumerate} 环境。
  \item[enumitem] 修改列表环境 \env{enumerate} 和 \env{itemize} 等的格式。
  \item[lettrine] 生成段落首字母大写的效果。
\end{pkglist}

\endinput