doc.tex

% !TeX encoding = UTF-8
% !TeX program = xelatex
% !TeX spellcheck = en_US

\documentclass[a4paper]{ltxdoc}

\usepackage[UTF8]{ctex}
\usepackage{unicode-math}
\usepackage{caption}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{listings}
\usepackage[perpage]{footmisc}
\usepackage{hypdoc}

\makeatletter

% 设置字体
\IfFileExists{/System/Library/Fonts/Times.ttc}{
  \setmainfont{Times}
  \setsansfont[Scale=MatchLowercase]{Helvetica}
  \setmonofont[Scale=MatchLowercase]{Menlo}
  \xeCJKsetwidth{‘’“”}{1em}
}{}
\unimathsetup{
  math-style=ISO,
  bold-style=ISO,
}
\IfFontExistsTF{xits-math.otf}{
  \setmathfont[
    Extension    = .otf,
    BoldFont     = *bold,
    StylisticSet = 8,
  ]{xits-math}
  \setmathfont[range={cal,bfcal},StylisticSet=1]{xits-math.otf}
}{
  \setmathfont[
    Extension    = .otf,
    BoldFont     = XITSMath-Bold,
    StylisticSet = 8,
  ]{XITSMath-Regular}
  \setmathfont[range={cal,bfcal},StylisticSet=1]{XITSMath-Regular.otf}
}

% 定义一些命令用于写文档
\newcommand\TeXLive{\TeX{} Live}
\newcommand\unicodechar[1]{U+#1（\symbol{"#1}）}
\DeclareRobustCommand\file{\nolinkurl}
\DeclareRobustCommand\env{\texttt}
\DeclareRobustCommand\pkg{\textsf}
\DeclareRobustCommand\cls{\textsf}
\DeclareRobustCommand\opt{\texttt}

% 在 doc 的基础上增加 option 的描述
\def\DescribeOption{\leavevmode\@bsphack\begingroup\MakePrivateLetters
  \Describe@Option}
\def\Describe@Option#1{\endgroup
              \marginpar{\raggedleft\PrintDescribeOption{#1}}%
              \SpecialEnvIndex{#1}\@esphack\ignorespaces}
\@ifundefined{PrintDescribeOption}
   {\def\PrintDescribeOption#1{\strut \MacroFont #1\ }}{}

% 调整列表的格式
\setlength\partopsep{\z@}
\def\@listi{\leftmargin\leftmargini
            \parsep \z@
            \topsep \z@
            \itemsep \z@}
\let\@listI\@listi
\@listi

% listings 的样式
\lstdefinestyle{lstshell}{
  basicstyle      = \small\ttfamily,
  backgroundcolor = \color{lightgray},
  language        = bash,
}
\newcommand\shellcmd[1]{\colorbox{lightgray}{\lstinline[style=lstshell]|#1|}}
\lstnewenvironment{shell}{\lstset{style=lstshell, gobble=2}}{}
\lstnewenvironment{latex}{%
  \lstset{
    basicstyle = \small\ttfamily,
    frame      = single,
    gobble     = 2,
    language   = [LaTeX]TeX,
  }%
}{}

\hypersetup{
  allcolors         = blue,
  bookmarksnumbered = true,
  bookmarksopen     = true,
}
\makeatother


\begin{document}



\title{\cls{xustthesis} 使用说明}
\author{GinShio\thanks{iris AT ginshio.org}}
% \author{Zeping Lee\thanks \and
%   }
\date{v3.2.1\qquad 2021-03-12}
\maketitle



\section{简介}

本模板 \cls{xustthesis} 是西安科技大学本科生和研究生学位论文的 \LaTeX{}
模板，基于 \href{https://github.com/ustctug/ustcthesis}{中国科学技术大学学位论文 LaTeX 模板} \textbf{v3.2.1} 修改，作者 \textbf{Zeping Lee}\footnote{zepinglee AT gmail.com} 和 \textbf{seisman}\footnote{seisman.info AT gmail.com} ，原中科大模板按照最新版的《\href{http://gradschool.ustc.edu.cn/ylb/material/xw/wdxz/32.pdf}
{中国科学技术大学研究生学位论文撰写手册}》和
《\href{http://www.teach.ustc.edu.cn/document/doc-administration/4032.html}
{关于本科毕业论文（设计）格式和统一封面的通知}》的要求编写。

其前身是中国科学技术大学本科论文模板（作者 XPS，最后维护 ywg）
和中国科学技术大学研究生论文模板（作者 Liuqs，主要维护 Liuqs、Guolicai）。
后来两模板进行了整合梳理，由 ywg 维护。
2015 年，seisman 和 zepinglee 基于 \pkg{ctex} 2.0 重新编写了模板。
2017 年，随着学校发布了新版的《撰写手册》，本模板也更新到 v3.0。

用户在使用 \pkg{xustthesis} 模板前，应先阅读学校的相关规范。
如果在使用的过程中遇到问题，可以阅读
\href{https://github.com/ustctug/ustcthesis/wiki}{ustcthesis 常见问题}，
或者在 \href{https://github.com/GinShio/xustthesis/issues}{GitHub Issues (xustthesis)}
中反馈。



\section{编译方法}


\subsection{文件组成}
本模板的主要文件如表~\ref{tab:files}：
\begin{table}[htb]
  \centering\small
  \caption{模板的文件组成}
  \label{tab:files}
  \begin{tabular}{lll}
    \toprule
    类别     & 文件                      & 说明                        \\
    \midrule
    模板文件 & \file{xustthesis.cls}     & 模板文件                    \\
             & \file{xust/}              & 校名和校徽图片              \\
    \midrule
    使用说明 & \file{doc.tex}            & 模板使用说明的源代码        \\
             & \file{doc.pdf}            & (你正在阅读的) 模板使用说明 \\
    \midrule
    示例文档 & \file{example/}           & 示例文档                    \\
             & \file{math-conmmands.tex} & 推荐使用的数学配置          \\
    \midrule
    其他     & \file{README.md}          & 基本说明                    \\
             & \file{latexmkrc}          & latexmk 的配置文件          \\
             & \file{Makefile}           & GNU make 的配置文件         \\
             & \file{.vscode/}           & VS Code 的配置文件          \\
    \bottomrule
  \end{tabular}
\end{table}

示例文档包括了常用的 \LaTeX{} 命令，建议新手从此入手，用自己的内容进行替换。


\subsection{依赖宏包}

本模板要求使用 TeX Live、MacTeX 或 MiKTeX 不低于 2017 年的发行版，
推荐升级到最新的版本。

模板直接依赖的宏包有：
\pkg{amsmath},
\pkg{caption},
\pkg{calc},
\pkg{color},
\pkg{ctex},
\pkg{fancyhdr},
\pkg{footmisc},
\pkg{geometry},
\pkg{graphicx},
\pkg{biblatex},
\pkg{notoccite},
\pkg{titletoc},
\pkg{url},
\pkg{unicode-math}。

另外，模板还对其他宏包提供了支持，包括：
\pkg{amsthm},
\pkg{algorithm2e},
\pkg{hyperref},
\pkg{nomencl},
\pkg{siunitx}。
这些宏包并非必需，用户可以根据需要选择使用。
模板在检测到这些宏包被调用后会自动进行配置。

注意，本模板\emph{不}兼容的宏包有：
\pkg{amsfonts},
\pkg{amssymb},
\pkg{natbib},
\pkg{bm},
\pkg{cite},
\pkg{mathrsfs},
\pkg{newtx},
\pkg{upgreek}。


\subsection{开始编译}

\begin{enumerate}

\item GNU make \\
Linux/Mac用户，可以直接使用 GNU make 工具，这是最简单的方法。
编译论文 \file{example.pdf}：
\begin{shell}
  make example
\end{shell}
编译说明文档 \file{doc.pdf}：
\begin{shell}
  make doc
\end{shell}
另外还可以用 \shellcmd{make clean} 清理辅助文件。

\item |latexmk| \\
Windows 用户可能无法使用GNU make，使用 |latexmk| 也是一个比较简单的方法，
配置文件由 \file{latexmkrc} 给出，其参数设置为 |-xelatex|，用户编译论文
只需使用命令：
\begin{shell}
  latexmk -xelatex example/example.tex
\end{shell}
编译说明文档：
\begin{shell}
  latexmk -xelatex doc.tex
\end{shell}
清理辅助文件可以用 \shellcmd{latexmk -c}。图形界面用户应参考编辑器的使用说明。

\item 手动编译 \\
手动编译是最繁琐的方法，用户可能需要运行多遍，以确保论文的交叉引用等信息全部正确。

编译论文 \file{example.pdf}：
\begin{shell}
  xelatex example/example.tex
  bibtex example.aux
  xelatex example/example.tex
  xelatex example/example.tex
\end{shell}
编译说明文档 \file{doc.pdf}：
\begin{shell}
  xelatex doc.tex
  xelatex tex
\end{shell}
\end{enumerate}



\section{模板设置}


\subsection{文档类参数}
\DescribeOption{degree}
选择学位，支持 \opt{bachelor}，\opt{master}，\opt{doctor}（默认）。
\begin{latex}
  \documentclass[degree=doctor]{xustthesis}
\end{latex}

\DescribeOption{degree-type}
学位类型。可选：学术型 \opt{academic}（默认），专业型 \opt{professional}。
\begin{latex}
  \documentclass[degree-type=professional]{xustthesis}
\end{latex}

\DescribeOption{language}
论文全文的主要语言。可选：\opt{chinese}（默认），\opt{english}。
\begin{latex}
  \documentclass[language=english]{xustthesis}
\end{latex}

\DescribeOption{output}
输出 PDF 的类型：
\begin{itemize}
  \item \opt{print}（默认）：用于双面打印纸质论文
  \item \opt{electronic}：单面，并保留超链接颜色
\end{itemize}
\begin{latex}
  \documentclass[output=electronic]{xustthesis}
\end{latex}

\DescribeOption{section-style}
本科生专用，章节标题的样式。可选：\opt{chinese}（默认），\opt{english}。
\begin{itemize}
  \item \opt{chinese}（默认）：汉字序号（例 1）
  \item \opt{arabic}：数字序号（例 2）
\end{itemize}
\begin{latex}
  \documentclass[section-style=arabic]{xustthesis}
\end{latex}


\subsection{字体设置}
模板默认可以自动检测操作系统，并配置改平台上合适的字体，
具体的配置策略如表~\ref{tab:font}。
\begin{table}[htb]
  \centering
  \caption{自动配置字体策略}
  \label{tab:font}
  \begin{tabular}{ccc}
    \toprule
    Windows         & macOS           & 其他            \\
    \midrule
    Times New Roman & Times New Roman & TeX Gyre Termes \\
    Arial           & Arial           & TeX Gyre Heros  \\
    Courier         & Menlo           & TeX Gyre Cursor \\
    中易宋体        & 华文宋体        & Fandol 宋体     \\
    中易黑体        & 华文黑体        & Fandol 黑体     \\
    \bottomrule
  \end{tabular}
\end{table}

然而自动配置的字体只能保证编译通过，但是还存在一些问题：
\begin{enumerate}
  \item 在其他平台上配置的 TeX Gyre 系列字体，虽然在风格上比较接近 Times 和 Arial，
    但是毕竟跟《撰写手册》要求的字体不完全一致；
  \item Fandol 字库的字形较少，常常出现缺字的情况；
  \item 华文字库和 Fandol 字库虽然不违反《撰写手册》的要求，
    但是其字形跟中易字库有所差别，这导致封面、标题的视觉效果与学校的 Word 示例不一致，
    可能被审查老师认为格式不符合要求。
\end{enumerate}

所以建议在提交最终版前使用 Windows 平台的字体进行编译。

用户也可以在调用模板时手动指定使用的字库，如：
\begin{latex}
  \documentclass[fontset=windows]{xustthesis}
\end{latex}
该选项会传递给 \pkg{ctex} 宏包进行处理，
允许的值包括 \opt{windows}、\opt{mac}、\opt{fandol}，
详见 \pkg{ctex}、\pkg{xeCJK}、\pkg{fontspec} 等宏包的使用说明。



\section{论文内容}

研究生论文的内容按照以下顺序排列：
\begin{description}
  \item[title page] 中文封面，英文封面，原创性声明及授权使用说明
  \item[front matter] 中、英文摘要，目录，图、表清单，符号说明
  \item[main matter] 正文章节，参考文献
  \item[appendix] 附录
  \item[back matter] 致谢，已发表论文列表
\end{description}

本科生论文的内容按照以下顺序排列：
\begin{description}
  \item[title page] 中文封面
  \item[front matter] 目录，中文摘要
  \item[main matter] 正文章节，参考文献，致谢
  \item[appendix] 附录
\end{description}

示例文档 \file{example.tex} 中的致谢、目录等章节的顺序，是按照研究生论文的格式组
织内容的，\emph{本科生需要手动调整顺序}。


\subsection{封面}

“封面”的名字让人有些混淆，它既可以指由印刷厂统一制作的硬皮封面（cover），也可
以指书打开后的第一页（title page）。在这里指的是后者，所以本模板从 title page
开始。

\DescribeMacro{\maketitle}
\DescribeMacro{\copyrightpage}
封面和声明页分别由 \cs{maketitle} 和 \cs{copyrightpage} 命令生成，
其中的各项信息使用 \cs{xustsetup} 命令的方式填写，如：
\begin{latex}
  \xustsetup{
    title  = {论文中文题目},
    title* = {Thesis English Title},
  }
\end{latex}
模板提供的选项见表~\ref{tab:covercmds}，
\begin{table}[htb]
  \centering\small
  \caption{录入封面信息的命令}
  \label{tab:covercmds}
  \begin{tabular}{lll}
    \toprule
    命令                & 命令（英文）         & 说明       \\
    \midrule
    \opt{title}         & \opt{title*}         & 论文标题   \\
    \opt{author}        & \opt{author*}        & 作者姓名   \\
    \opt{major}         & \opt{major*}         & 学科专业   \\
    \opt{supervisor}    & \opt{supervisor*}    & 导师姓名   \\
    \opt{date}          & -                    & 完成时间   \\
    \opt{secret-level}  & \opt{secret-level*}  & 密级       \\
    \opt{secret-year}   & -                    & 保密年限   \\
    \bottomrule
  \end{tabular}
\end{table}

有几点说明：
\begin{itemize}
  \item \cs{xustsetup} 使用 \pkg{kvsetkeys} 机制，配置项之间不能有空行，否则会报错。
  \item 导师姓名 \opt{supervisor} 允许多个姓名，使用“,”（西文逗号 U+002C）隔开。
  \item 完成时间 \opt{date} 应使用 ISO 格式，默认为当前日期。
  \item 其中带 |*| 后缀的选项用于设置英文封面。
\end{itemize}


\subsection{摘要和章节}
\DescribeEnv{abstract}
\DescribeEnv{enabstract}
\DescribeEnv{notation}
\DescribeEnv{acknowledgements}
\DescribeEnv{publications}
对于特殊的章节，\cls{xustthesis} 还提供了相应的环境：
\begin{itemize}
  \item 中文摘要：\env{abstract}
  \item 英文摘要：\env{enabstract}
  \item 符号说明：\env{notation}
  \item 致谢：    \env{acknowledgements}
  \item 发表成果：\env{publications}
\end{itemize}

\DescribeOption{keywords}
\DescribeOption{keywords*}
摘要的关键词应使用 \cs{xustsetup} 的接口进行设置，
只要在摘要结束前即可，比如：
\begin{latex}
  \begin{abstract}
    这里是摘要。
    \xustsetup{keywords = {论文；摘要；关键词}}
  \end{abstract}
\end{latex}

\DescribeMacro{\tableofcontents}
\DescribeMacro{\listoffigures}
\DescribeMacro{\listoftables}
目录和图、表清单可以使用命令自动生成：
\begin{itemize}
  \item 目录：  \cs{tableofcontents}
  \item 图清单：\cs{listoffigures}
  \item 表清单：\cs{listoftables}
\end{itemize}


\subsection{浮动体}

《撰写手册》要求图题置于图的下方，表题置于表的上方。
\LaTeX{} 的 \cs{caption} 命令并不能控制在浮动体中的位置，
需要作者注意写在合适的地方。

\DescribeMacro{\note}
本模板还提供了 \cs{note}\marg{notes} 命令，用于在图表中添加注释。

关于图片的并排，推荐使用较新的 \pkg{subcaption} 宏包，不建议使用
\pkg{subfigure} 或 \pkg{subfig}。

更多的表格样式参见 \pkg{booktabs}（三线表）、\pkg{longtable}（跨页表格）。

算法可以使用 \pkg{algorithms} 宏包，推荐使用较新的 \pkg{algorithm2e}。


\subsection{数学}

\DescribeMacro{\symup}
\DescribeMacro{\symbf}
《撰写手册》要求数学符号要根据 GB/T 3102.11-1993《物理科学和技术中使用的数学符号》
\footnote{原 GB 3102.11-1993，根据2017年第7号公告和强制性标准整合精简结论，自2017年3月23日起,该标准转化为推荐性标准。}
使用，
这与 \LaTeX{} 默认的英美国家的数学符号习惯有所差异。
本模板基于 \pkg{unicode-math} 宏包配置数学符号，以遵循国标的规定：
\begin{enumerate}
  \item 大写希腊字母默认为斜体，如 \cs{Delta}：$\Delta$。
  \item 有限增量符号 $\increment$（U+2206）应使用 \cs{increment} 命令。
  \item 向量、矩阵和张量要求粗斜体，应使用 \cs{symbf} 命令，
    如 |\symbf{A}|、|\symbf{\alpha}|。
  \item 数学常数和特殊函数使用正体，
    如圆周率 $\symup{\pi}$、$\symup{\Gamma}$ 函数。
    应使用 \pkg{unicode-math} 宏包提供的 \cs{symup} 命令转为正体，
    如 |\symup{\pi}|。
  \item 微分符号 $\mathrm{d}$ 使用正体，本模板提供了 \cs{dif} 命令。
\end{enumerate}

注意，\pkg{unicode-math} 宏包与 \pkg{amsfonts}, \pkg{amssymb}, \pkg{bm},
\pkg{mathrsfs}, \pkg{upgreek} 等宏包\emph{不}兼容。
本模板作了处理，用户可以直接使用 \cs{bm}, \cs{mathscr},
\cs{upGamma}。

关于数学符号更多的用法，参见
\href{http://mirrors.ctan.org/macros/latex/contrib/unicode-math/unicode-math.pdf}{\pkg{unicode-math}}
宏包的使用说明和符号列表
\href{http://mirrors.ctan.org/macros/latex/contrib/unicode-math/unimath-symbols.pdf}{\pkg{unimath-symbols}}。


\subsection{参考文献}

按照《撰写手册》和 GB/T 7714-2015《信息与文献\ 参考文献著录规则》 的规定，
参考文献的标注体系分为“顺序编码制”和“著者-出版年制”（authoryear），
《撰写手册》推荐使用顺序编码制。如需设置样式请参见 \href{https://github.com/hushidong/biblatex-gb7714-2015}{biblatex-gb7714-2015}

\DescribeMacro{\cite}
在正文中引用文献时应使用 \cs{cite} 命令。
同一处引用多篇文献时，需要将各篇文献的 key 一同写在参数中，
如 |\cite{knuth84,lamport94,mittelbach04}|。
它可以自动排序并用处理连续编号。
更多的引用标注方法可以参考 \pkg{biblatex} 宏包的使用说明。

\DescribeMacro{\inlinecite}
\DescribeOption{cite-style}
在使用角标数字式时，如果文献序号作为叙述文字的一部分，
需要临时将文献序号与正文平排，
可以使用 \cs{inlinecite} 命令临时使用正文模式的引用标注，如：
\begin{latex}
  文献~\inlinecite{knuth84} 提出了一种新的断行算法
\end{latex}
也可以在正文开始处统一切换全文的引用标注样式：
\begin{latex}
  \xustsetup{}
    cite-style = inline,
  }
\end{latex}

若需要标出引文的页码，可以标在 \cs{cite} 的可选参数中，如 |\cite[42]{abc}|。

\DescribeMacro{\citep}
\DescribeMacro{\citet}
在采用著者-出版年制时，如果将著者姓氏和出版年都置于“( )”内，
应使用 \cs{citep} 命令代替 \cs{cite} 来引用；
如果将著者姓氏作为正文的一部分，在其后的“( )”内只著录出版年，
则应使用 \cs{citet} 命令。

\DescribeMacro{\printbibliography}
参考文献表可以使用 \BibTeX{} 生成，并在文中使用 \cs{printbibliography} 命令调用。
\BibTeX{} 默认情况下可以自动识别文献语言，并自动处理文献类型和载体类型标识，
但是在少数情况下需要用户手动指定，如：
\begin{latex}
  @misc{citekey,
    language = {japanese},
    mark     = {Z},
    medium   = {DK},
    ...
  }
\end{latex}
可选的语言有 english, chinese, japanese, russian。

注意，国标规定参考文献表采用著者-出版年制组织时，各篇文献首先按文种集中，
然后按著者字顺和出版年排列；
中文文献可以按著者汉语拼音字顺排列，也可以按著者的笔画笔顺排列。
然而由于 \BibTeX{} 功能的局限性，无法自动获取著者姓名的拼音或笔画笔顺，
所以\emph{必须}在 bib 数据库中的 |key| 域手动录入著者姓名的拼音，如：
\begin{latex}
  @book{capital,
    author = {马克思 and 恩格斯},
    key    = {ma3 ke4 si1   en1 ge2 si1},
    ...
  }
\end{latex}

\BibTeX{} 对自定义样式的支持比较有限，
所以用户只能通过修改 \file{bst} 文件来修改文献列表的格式。
本宏包提供了一些接口供用户更方便地修改。

在 \file{bst} 文件开始处的 |load.config| 函数中，
有一组配置参数用来控制样式，表~\ref{tab:config} 列出了每一项的默认值和功能。
若变量被设为 |#1| 则表示该项被启用，设为 |#0| 则不启用。
默认的值是严格遵循《撰写手册》的配置。

\begin{table}[htb]
\centering\small
\caption{参考文献表样式的配置参数}
\label{tab:config}
\begin{tabular}{lcl}
  \toprule
  参数值                         & 默认值 & 功能                           \\
  \midrule
  uppercase.name                 & |#1|   & 将著者姓名转为大写             \\
  max.num.authors                & |#3|   & 输出著者的最多数量             \\
  period.between.author.year     & |#0|   & 著者和年份之间使用句点连接     \\
  sentence.case.title            & |#1|   & 将西文的题名转为 sentence case \\
  link.title                     & |#0|   & 在题名上添加 url 的超链接      \\
  show.mark                      & |#1|   & 显示文献类型标识               \\
  italic.journal                  & |#0|   & 西文期刊名使用斜体             \\
  show.missing.address.publisher & |#1|   & 出版项缺失时显示“出版者不详”   \\
  show.url                       & |#1|   & 显示 url                       \\
  show.doi                       & |#1|   & 显示 doi                       \\
  show.note                      & |#0|   & 显示 note 域的信息             \\
  \bottomrule
\end{tabular}
\end{table}

如果需要每章生成独立的参考文献表，可以使用 \pkg{chapterbib} 宏包，
但是需要注意：
\begin{enumerate}
  \item 在 \file{example.tex} 中调用每章的子文件时必须使用 \cs{include} 命令；
  \item 每章需要使用 \cs{bibliographystyle} 和 \cs{bibliography} 命令；
  \item 如果手动调用 BibTeX，需要对每章生成的 \file{.aux} 文件编译，
    （如果使用 \pkg{latexmk} 则可以自动处理）。
\end{enumerate}



\end{document}