% !TeX root = ../exam-zh-doc-basic.tex

\section{常见问题 FAQ}

本章收集了用户在使用 \cls{exam-zh} 时最常遇到的问题。建议遇到问题时先在这里查找答案。

\subsection{安装与编译问题}

\subsubsection{Q1: 如何确认 exam-zh 安装成功？}

创建一个测试文件，输入：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}
  \begin{document}
    测试成功
  \end{document}
\end{latexcode}

使用 \cmd{xelatex} 编译，如果生成 PDF 并显示"测试成功"，说明安装成功。

\subsubsection{Q2: 数学公式编译错误}

\textbf{错误原因：}在普通文本中使用了数学符号但没有用 |$| 包裹。

常见报错是：|Missing \$ inserted|。

\textbf{错误示例：}

\begin{latexcode}
  计算结果是 x^2  % 错误：x^2 是数学符号
\end{latexcode}

\textbf{正确写法：}

\begin{latexcode}
  计算结果是 $x^2$  % 正确：用 $ $ 包裹数学公式
\end{latexcode}

\subsubsection{Q3: 中文无法显示或显示乱码}

\textbf{可能原因及解决方案：}

\begin{enumerate}
  \item \textbf{使用了错误的编译器}
    \begin{itemize}
      \item 必须使用 \cmd{xelatex}，不能用 \cmd{pdflatex}
      \item 检查 IDE 设置或命令行命令
    \end{itemize}

  \item \textbf{文件编码不是 UTF-8}
    \begin{itemize}
      \item 确保源文件以 UTF-8 编码保存
      \item 大多数现代编辑器默认 UTF-8，旧版 Windows 记事本可能不是
    \end{itemize}

  \item \textbf{缺少中文字体}
    \begin{itemize}
      \item \TeX{} Live 通常自带中文字体
      \item 可以手动指定字体：\cmd{\textbackslash{}setCJKmainfont\{SimSun\}}
    \end{itemize}
\end{enumerate}

\subsubsection{Q4: 为什么必须用 XeLaTeX？}

\textbf{原因：}

\begin{itemize}
  \item \XeLaTeX{} 原生支持 Unicode，能正确处理中文
  \item 可以直接使用系统字体
  \item 支持现代 OpenType 字体特性
  \item \pdfLaTeX{} 对中文支持较差，需要复杂配置
\end{itemize}

\subsubsection{Q5: 如何在 Overleaf 上使用？}

在文档\textbf{最开头}添加一行代码：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \let\stop\empty  % 添加这一行
  \documentclass{exam-zh}
  % ... 其余内容
\end{latexcode}

然后在 Overleaf 中选择 \XeLaTeX{} 编译器。

\subsubsection{Q6: TeX Live 2020/2021 编译失败怎么办？}

\textbf{错误现象：}编译时提示 |LaTeX3 Error: The key property '.str_set:N' is unknown|

\textbf{原因：}\LaTeX3 版本过旧，与 \cls{exam-zh} 不兼容。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{升级到 \TeX{} Live 2022 或更新版本}（推荐）
    \begin{shellcode}[morekeywords={tlmgr,update}]
  # 更新 TeX Live 管理器
  tlmgr update --self --all
    \end{shellcode}

  \item \textbf{或者升级 \LaTeX3 核心包}
    \begin{shellcode}[morekeywords={tlmgr,update}]
  tlmgr update l3kernel l3packages
    \end{shellcode}
\end{enumerate}

\textbf{推荐：}使用 \TeX{} Live 2023 或 2024 以获得最佳兼容性。

\subsubsection{Q7: latexmk 编译陷入无限循环}

\textbf{问题：}使用 |latexmk -xelatex| 命令编译时，程序不停地重复编译。

\textbf{原因：}某些版本的 \cls{exam-zh} 存在辅助文件处理 bug。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更新到最新版本}
    \begin{shellcode}[morekeywords={tlmgr,update}]
  tlmgr update exam-zh
    \end{shellcode}

  \item \textbf{或使用手动编译}
    \begin{shellcode}[morekeywords={xelatex}]
  xelatex yourfile.tex
  xelatex yourfile.tex  # 编译两次以更新目录和引用
    \end{shellcode}
\end{enumerate}

\subsubsection{Q8: 试卷合集里不想显示 \textbackslash chapter 标题页怎么办？}

如果你把多份试卷放在同一个文件里，并且使用 |\chapter| 分隔每一份试卷，可以通过下面的键值隐藏章节标题页：

\begin{latexcode}
  \examsetup{
    page/show-chapter = false
  }
\end{latexcode}

这样 |\chapter| 仍然会用于分隔试卷并重置题号，但不会额外排出章节标题页。

\subsubsection{Q9: choices 环境排版异常怎么办？}

\textbf{先检查这几项：}

\begin{enumerate}
  \item 是否使用了 \XeLaTeX{} 编译；
  \item 是否在两层及以上的列表环境里嵌套了 |choices|；
  \item 是否在 |choices| 前后混用了复杂图文绕排。
\end{enumerate}

\textbf{常见解决方法：}

\begin{enumerate}
  \item 手动指定列数：
    \begin{latexcode}
  \begin{choices}[columns = 1]
    \item ...
  \end{choices}
    \end{latexcode}

  \item 把选择题放在较外层，避免深层嵌套列表；

  \item 图文题优先使用 |\textfigure|、|multifigures| 或普通 |\includegraphics|，不要把复杂绕排和 |choices| 混在一起。
\end{enumerate}


\subsection{功能使用问题}

\subsubsection{Q10: 如何控制选项列数？}

\textbf{自动模式（推荐）：}

选项会根据内容长度自动排列，无需手动设置。

\textbf{手动指定：}

\begin{latexcode}
  \examsetup{
    choices/columns = 2  % 强制排成2列
  }
\end{latexcode}

或者只对某一题设置：

\begin{latexcode}
  \begin{choices}[columns = 4]  % 这一题排成4列
    \item ...
  \end{choices}
\end{latexcode}

\subsubsection{Q11: 如何生成教师版和学生版？}

\textbf{方法一：}通过注释切换

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  % 显示答案（教师版）
  \examsetup{
    question/show-answer = true
  }

  % 隐藏答案（学生版）- 注释掉上面的 \examsetup 即可
\end{latexcode}

\textbf{方法二：}使用条件编译（高级）

在文档开头定义：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \newif\ifteacher  % 定义教师版开关
  \teachertrue      % 教师版：改为 \teachertrue
  % \teacherfalse   % 学生版：改为 \teacherfalse

  \ifteacher
    \examsetup{
      question/show-answer = true
    }
  \fi
\end{latexcode}

\subsubsection{Q12: 填空题下划线长度如何调整？}

\textbf{全局设置：}

\begin{latexcode}
  \examsetup{
    fillin/width = 4em  % 设置默认宽度为 4em
  }
\end{latexcode}

\textbf{单独设置：}

\begin{latexcode}
  \fillin[width = 6em][答案]  % 这个填空宽度是 6em
\end{latexcode}

\subsubsection{Q13: 如何修改密封线样式？}

\textbf{完全隐藏密封线：}

\begin{latexcode}
  \examsetup{
    sealline/show = false
  }
\end{latexcode}

\textbf{调整密封线位置和样式：}

\begin{latexcode}
  \examsetup{
    sealline/show = true,
    sealline/scope = firstpage,         % 只在第一页显示
    sealline/line-thickness = 1pt,      % 线条粗细
    sealline/text = {密封线内不要答题},   % 文字内容
  }
\end{latexcode}

详细说明见完整文档。

\subsubsection{Q14: 分值不显示怎么办？}

\textbf{问题：}设置了 \cmd{[points = 10]} 但看不到分值。

\textbf{原因：}默认不显示分值。

\textbf{解决：}

\begin{latexcode}
  \examsetup{
    question/show-points = true  % 显示分值
  }
\end{latexcode}

\subsubsection{Q15: 如何实现答案后置/集中显示？}

\textbf{需求：}希望选择题答案 |\paren[]| 和填空题答案 |\fillin[]| 能像解答题一样，集中显示在试卷末尾。

\textbf{当前状态：}\cls{exam-zh} 目前\textbf{不支持}此功能。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{手动整理答案}
    \begin{latexcode}
  % 在文档末尾添加答案页
  \newpage
  \section*{参考答案}
  \begin{enumerate}
    \item C  % 第1题答案
    \item B  % 第2题答案
    \item 3.14  % 第3题填空答案
  \end{enumerate}
    \end{latexcode}

  \item \textbf{使用注释记录}
    \begin{latexcode}
  \begin{question}
    $1 + 1 = $ \paren[C]  % 答案：C
    \begin{choices}
      \item $0$ \item $1$ \item $2$ \item $3$
    \end{choices}
  \end{question}
    \end{latexcode}
    然后手动提取注释中的答案。
\end{enumerate}

\subsection{排版问题}

\subsubsection{Q16: 题号对齐不整齐}

\textbf{问题：}想修改题号样式，或者担心题号位看起来不整齐。

\textbf{做法：}使用真实存在的 |question/label| 键值修改题号格式：

\begin{latexcode}
  \examsetup{
    question/label = \arabic*.,   % 1. 2. 3.
    % question/label = (\arabic*), % (1) (2) (3)
    % question/label = \Alph*.,    % A. B. C.
  }
\end{latexcode}

\textbf{说明：}模板会根据题号样式自动设置标签宽度，仓库里没有 |question/label-width| 这个键值。

\subsubsection{Q17: 填空题下划线超出页面边界}

\textbf{问题：}填空内容较长时，如何避免答案或占位线超出页面边界？

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{显示长答案时直接使用 |\fillin|}
    \begin{latexcode}
  计算结果为 \fillin[这是一个比较长的答案内容，需要换行显示]
    \end{latexcode}
    当答案自然宽度超过当前行宽时，模板会自动换行；如需无条件使用可换行排版，可改用 |\fillin*|。

  \item \textbf{手动控制占位宽度}
    \begin{latexcode}
  \fillin[width = 5em][答案]
    \end{latexcode}

  \item \textbf{不显示答案时配合宽度设置}
    \begin{latexcode}
  \examsetup{question/show-answer = false}
  \fillin[width = 1.2\linewidth][长答案]
    \end{latexcode}
\end{enumerate}

\textbf{提示：}如果是数学答案，仍然要写成 |\fillin[$x^2+1$]| 这种数学模式形式。

\subsubsection{Q18: 填空题答案中使用区间符号 [2,3) 报错}

\textbf{错误信息：}使用 |\fillin[[2,3)]| 时编译报错。

\textbf{原因：}方括号 |[]| 被解析为可选参数的定界符，与答案内容的括号冲突。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{用花括号包裹答案}（推荐）
    \begin{latexcode}
  答案是 \fillin[{$[2,3)$}]
    \end{latexcode}

  \item \textbf{避免直接写未配对的方括号}
    \begin{latexcode}
  答案是 \fillin[$\{2 \leq x < 3\}$]  % 用集合表示
    \end{latexcode}
\end{enumerate}

\subsubsection{Q19: wrapstuff 图文绕排在复杂环境中报错}

\textbf{问题：}在 |problem| 环境内使用两层 |enumerate| 后，图文绕排容易出问题。

\textbf{错误示例：}

\begin{latexcode}
  \begin{problem}
    \begin{enumerate}
      \item 第一问
        \begin{enumerate}
          \item 小问 (a)
            \begin{wrapstuff}  % 此处会报错
              \includegraphics{fig.png}
            \end{wrapstuff}
        \end{enumerate}
    \end{enumerate}
  \end{problem}
\end{latexcode}

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{避免过度嵌套}：不要在两层以上的列表环境中使用图文绕排

  \item \textbf{使用 minipage}（推荐）
    \begin{latexcode}
  \begin{minipage}[t]{0.6\linewidth}
    题目文字内容...
  \end{minipage}%
  \begin{minipage}[t]{0.35\linewidth}
    \includegraphics[width=\linewidth]{fig.png}
  \end{minipage}
    \end{latexcode}

  \item \textbf{将图片放在环境外部}：先结束嵌套环境，再插入图片
\end{enumerate}

\textbf{注意：}复杂图文题建议优先使用 |\textfigure|、|multifigures| 或普通 |minipage|。

\subsubsection{Q20: 自动换页后行距变大}

\textbf{问题：}偶尔在自动换页时，新页面的行距异常增大。

\textbf{原因：}\LaTeX{} 的页面垂直对齐机制导致，无法完全避免。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{手动调整}
    \begin{latexcode}
  % 在行距变大的地方添加
  \vspace{-1em}  % 调整负间距
    \end{latexcode}

  \item \textbf{强制换页}
    \begin{latexcode}
  % 在合适的位置手动换页
  \newpage
    \end{latexcode}

  \item \textbf{调整内容}：删减或增加部分内容，改变自然换页位置
\end{enumerate}

\subsubsection{Q21: 如何整体缩小行距以节约纸张？}

\textbf{需求：}让试卷排版更紧凑，节约打印纸张。

\textbf{全局调整行距：}

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  % 方法1：使用 \linespread
  \linespread{0.9}  % 行距缩小到 90%

  % 方法2：使用 setspace 宏包
  \usepackage{setspace}
  \setstretch{0.85}  % 更精细的控制
\end{latexcode}

\textbf{调整题目间距：}

\begin{latexcode}
  \examsetup{
    question/top-sep = 0.2em,
    question/bottom-sep = 0.2em,
  }
\end{latexcode}

\textbf{调整选项间距：}

\begin{latexcode}
  \examsetup{
    choices/linesep = 0.3em,     % 多行选项之间的额外间距
    choices/column-sep = 0.8em,  % 列间距
  }
\end{latexcode}

\textbf{注意：}行距过小可能影响阅读体验，建议不要低于 0.8。

\subsubsection{Q22: 选项自动换行出问题}

\textbf{问题：}选项内容很长，自动换行后排版混乱。

\textbf{建议：}

\begin{enumerate}
  \item 精简选项文字
  \item 手动设置为单列：|\begin{choices}[columns = 1]|
  \item 使用 \cmd{linebreak} 手动换行
\end{enumerate}

\subsubsection{Q23: 数学公式显示异常}

\textbf{常见问题：}

\begin{enumerate}
  \item \textbf{公式不显示}
    \begin{itemize}
      \item 检查是否用 \$ 包裹公式
      \item 例如：|\$x^2\$| 而不是 |x^2|
    \end{itemize}

  \item \textbf{公式中中文不显示}
    \begin{itemize}
      \item 使用 |\text{}| 包裹中文
      \item 例如：|\$x > 0\text{时}\$|
    \end{itemize}

  \item \textbf{分数不显示}
    \begin{itemize}
      \item 使用 |\frac{分子}{分母}|
      \item 例如：|\$\frac{1}{2}\$|
    \end{itemize}
\end{enumerate}

\subsubsection{Q24: \textbackslash Omega 或 \textbackslash varnothing 等数学符号显示异常}

\textbf{问题：}某些希腊字母或特殊数学符号显示不正确或缺失。

\textbf{原因：}数学字体配置问题。

\textbf{补充：}\cls{exam-zh} 默认从 Asana Math 单独取用 |\varnothing| 的字形，
以避免切换 |math-font| 时空集符号外观随之改变。这只是一项单符号覆盖，
并不代表模板加载或完整支持 \pkg{mtpro2}。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更换数学字体}
    \begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \examsetup{
    math-font = xits,  % 也可以改成 stix、libertinus、lm 等
  }
    \end{latexcode}

  \item \textbf{使用替代符号}
    \begin{itemize}
      \item |\varnothing| 显示异常时，先确认 TeX 发行版包含 Asana Math；也可使用 |\emptyset|
      \item 先确认自己处在数学模式中，例如 |\$\\Omega\$|
    \end{itemize}
\end{enumerate}

\subsubsection{Q25: 概率统计中波浪号 \textasciitilde{} 无法使用}

\textbf{问题：}在数学模式中输入 |X ~ N(0,1)| 时报错或显示异常。

\textbf{原因：}|\~| 是特殊字符，表示上标波浪号或不间断空格。

\textbf{解决方案：}

\begin{latexcode}
  % 错误写法
  $X ~ N(0,1)$

  % 正确写法：使用 \sim 命令
  $X \sim N(0,1)$

  % 或使用 \thicksim（更粗的波浪号）
  $X \thicksim N(0,1)$
\end{latexcode}

\subsubsection{Q26: 向量箭头样式能否按大小写分别设置？}

\textbf{当前状态：}仓库里没有提供“按字母大小写分别设置向量箭头长度”的内置接口。

\textbf{建议：}

\begin{itemize}
  \item 如果只需要默认样式，直接使用 |\vec{a}|；
  \item 如果确实需要特殊箭头样式，建议在自己的文档里单独重定义，而不要把它当成 \cls{exam-zh} 的内置功能。
\end{itemize}

\subsubsection{Q27: 与 listings 或其他代码环境冲突}

\textbf{问题：}在选择题或题目中使用 |lstlisting| 等代码环境时报错。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更新到最新版本}：部分兼容性问题已在新版本中修复

  \item \textbf{使用 verbatim 代替}
    \begin{latexcode}
  \begin{question}
    以下代码的输出是：\paren[B]
    \begin{verbatim}
print("Hello")
    \end{verbatim}
  \end{question}
    \end{latexcode}

  \item \textbf{使用 listings 的内联模式}
    \begin{latexcode}
  \begin{question}
    命令 \lstinline|print("Hello")| 的作用是？
  \end{question}
    \end{latexcode}
\end{enumerate}

\subsubsection{Q28: 如何切换西文或数学字体？}

\textbf{做法：}使用 |\examsetup| 里的 |font| 和 |math-font| 键值：

\begin{latexcode}
  \examsetup{
    font = times,
    math-font = xits,
  }
\end{latexcode}

\textbf{说明：}可选值以完整文档为准，常见的有 |newcm|、|lm|、|times|、|stix|、|xits|、|libertinus| 等。

\subsubsection{Q29: 如何插入图片？}

\textbf{基本用法：}

\begin{latexcode}
  \includegraphics[width=5cm]{图片文件名.jpg}
\end{latexcode}

\textbf{说明：}\cls{exam-zh} 已经加载了图文相关模块，通常可以直接使用 |\includegraphics|。

\textbf{在题目中使用：}

\begin{latexcode}
  \begin{question}
    如图所示，计算三角形面积。
    \begin{center}
      \includegraphics[width=4cm]{triangle.pdf}
    \end{center}
  \end{question}
\end{latexcode}

\textbf{图文混排：}

参考完整文档中"图文排版"章节。

\subsubsection{Q30: 如何调整页边距？}

\textbf{全局设置：}

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \AtEndPreamble{
    \geometry{
      top = 2.5cm,
      bottom = 2cm,
      left = 2cm,
      right = 2cm
    }
  }
\end{latexcode}

\textbf{使用预设：}

\begin{latexcode}
  \examsetup{
    page/size = a4paper,  % 纸张大小
  }
\end{latexcode}


\subsection{获取帮助}

如果以上 FAQ 没有解决你的问题，可以通过以下方式获取帮助：

\subsubsection{查阅文档}

\begin{enumerate}
  \item \textbf{本文档}：\file{exam-zh-doc-basic.pdf}（入门指南）
  \item \textbf{完整文档}：\file{exam-zh-doc.pdf}（详细 API 参考）
  \item \textbf{LaTeX 入门}：\href{https://ctan.org/pkg/lshort-chinese}{lshort-zh-cn}
\end{enumerate}

\subsubsection{在线提问}

\textbf{GitHub/Gitee Issues：}

\begin{itemize}
  \item GitHub: \url{https://github.com/xkwxdyy/exam-zh/issues}
  \item Gitee: \url{https://gitee.com/xkwxdyy/exam-zh/issues}
\end{itemize}

\textbf{QQ 群：}652500180

\subsubsection{提问前的准备}

为了快速得到帮助，提问时请提供：

\begin{enumerate}
  \item \textbf{系统信息}：操作系统、\TeX{} 发行版版本
  \item \textbf{问题描述}：清楚描述遇到的问题
  \item \textbf{最小可复现示例}：能重现问题的最简代码
  \item \textbf{错误信息}：完整的错误提示（\emph{请勿用手机拍照}）
  \item \textbf{期望结果}：你想要达到的效果
\end{enumerate}

\textbf{提问模板：}

\begin{latexcode}
  系统：macOS / Windows / Linux
  TeX 发行版：TeX Live 2024
  exam-zh 版本：v0.26

  问题描述：
    我想实现...，但是出现了...

  最小可复现代码：
    \documentclass{exam-zh}
    \begin{document}
      ...（能重现问题的代码）
    \end{document}

  错误信息：
    ...（复制粘贴错误文本）

  期望效果：
    我希望能...
\end{latexcode}

详细的提问指南见附录"如何提问"。