% Documentation for pkuthss.
%
% Copyright (c) 2008-2009 solvethis
% Copyright (c) 2010-2019,2021-2022,2024 Casper Ti. Vector
%
% This work may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3 of this license or (at
% your option) any later version.
% The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX version
% 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% The current maintainer of this work is Casper Ti. Vector.
%
% This work consists of the following files:
%   pkuthss.tex
%   pkuthss.bib
%   chap/pkuthss-copy.tex
%   chap/pkuthss-abs.tex
%   chap/pkuthss-intro.tex
%   chap/pkuthss-chap1.tex
%   chap/pkuthss-chap2.tex
%   chap/pkuthss-chap3.tex
%   chap/pkuthss-concl.tex
%   chap/pkuthss-encl1.tex
%   chap/pkuthss-ack.tex

\chapter{pkuthss 文档模版提供的功能}
\section{pkuthss 文档类提供的选项}\label{sec:options}

除非特别说明，否则这一节提到的选项中都是不带“\verb|no|”的版本被启用。

\begin{itemize}
	\item \textbf{\texttt{[no]uppermark}}：
		是否在页眉中将章节名中的小写字母转换为大写字母。
		就目前而言，这样的转换存在着一些较为严重的缺陷\footnote{%
			准确地说是 \texttt{\string\MakeUppercase} 宏的问题：
			其在某些地方的转换不够健壮，
			例如 \texttt{\string\cite\string{ctex\string}}
			会被转换成 \texttt{\string\cite\string{CTEX\string}}。%
		}，因此不建议使用。
		基于上述考虑，\myemph{%
			pkuthss 文档类默认启用 \texttt{nouppermark} 选项，
			即不在页眉中使用大写的章节名%
		}。

	\item \textbf{\texttt{[no]pkufont}}：
		是否根据学校对论文格式的要求\cupercite{pku-thesisstyle}%
		将西文字体改为类似于 Times New Roman / Arial 的字体。

	\item \textbf{\texttt{[no]pkufoot}}\footnote{%
			此选项等价于 1.6.4 及以前版本 pkuthss-extra 宏包的
			\texttt{[no]footfmt} 选项；
			更改名称是为了使文档类选项名更加规则。%
		}：
		是否根据学校对论文格式的要求\cupercite{pku-thesisstyle}%
		修改和脚注相关的一些格式。
		具体地说，启用 \verb|pkufoot| 选项后会进行以下几项设置：
	\begin{itemize}
		\item 脚注参用带圈的编号。
		\item 页脚中脚注编号使用正文（而非上标）字体。
		\item 页脚中脚注编号和脚注文本之间默认间隔一个空格。
	\end{itemize}

	\item \textbf{\texttt{[no]pkuspace}}：
		是否根据学校对论文格式的要求\cupercite{pku-thesisstyle}%
		修改排版中的一些间距及相关设置。
		具体地说，启用 \verb|pkuspace| 选项后会按
		\parencite{pku-thesisstyle} 中的要求修改以下几项设置：
	\begin{itemize}
		\item 正文的行距。
		\item 目录中条目的缩进方式。
		\item 图表标题的字号，以及标题中编号和标题文字之间的间隔方式
			（例如图 \ref{fig:example} 所示）。
	\end{itemize}

	\begin{figure}[htbp!]
		\centering
		\includegraphics[width = 0.5\textwidth]{pkuword}
		\caption{示例插图}\label{fig:example}
	\end{figure}

	\item \textbf{\texttt{[no]spacing}}\footnote{%
			因为代码重构的缘故，
			此选项同时提供 1.5.5 及以前版本 pkuthss-extra 宏包
			中 \texttt{[no]tightlist} 选项所提供的功能。%
		}：
		是否采用一些常用的调整间距的额外版式设定。
		具体地说，启用 \verb|spacing| 选项后会进行以下几项设置：
	\begin{itemize}
		\item 调用 setspace 宏包以使某些细节处的空间安排更美观。
		\item 采用比 \hologo{LaTeX} 默认设定更加紧密的枚举环境%
			\footnote{%
				在枚举环境（itemize、enumerate 和 description）中，
				每个条目的内容较少时，条目往往显得稀疏；
				在参考文献列表中也有类似的现象。
				启用 \texttt{spacing} 选项后，
				将去掉这些环境中额外增加的（垂直）间隔。%
			}。
		\item 调整枚举环境的缩进，以适应中文排版中的习惯。
	\end{itemize}

	\item \textbf{\texttt{[no]spechap}}\footnote{%
			“spechap”是“\textbf{spec}ial \textbf{chap}ter”的缩写。%
		}：
		是否启用第 \ref{ssec:misc} 小节中介绍的 \verb|\specialchap| 命令。

	\item \textbf{\texttt{[no]pdftoc}}\footnote{%
			此选项部分等价于 1.4 alpha2 及以前版本 pkuthss-extra 宏包
			的 \texttt{[no]tocbibind} 选项。
			因为 tocbibind 宏包和 biblatex 宏包冲突，%
			pkuthss 文档类不再调用 tocbibind 宏包。%
		}：
		启用 \verb|pdftoc| 选项后，
		用 \verb|\tableofcontents| 命令生成目录时会自动添加“目录”的 pdf 书签。

	\item \textbf{\texttt{[no]pdfprop}}：
		是否自动根据设定的论文文档信息（如作者、标题等）
		设置生成的 pdf 文档的相应属性。\myemph{%
			注意：该选项实际上是在 \texttt{\string\maketitle} 时生效的，
			这是因为考虑到
			通常用户在调用 \texttt{\string\maketitle} 前
			已经设置好所有的文档信息。
			若用户不调用 \texttt{\string\maketitle}，
			则须在设定完文档信息之后自行调用
			第 \ref{ssec:misc} 小节中介绍的
			\texttt{\string\setpdfproperties} 命令以完成
			pdf 文档属性的设定。%
		}

	\item \textbf{其余文档类选项}：%
		pkuthss 文档类以 ctexbook 文档类为基础，
		其接受的其余所有文档类选项均被传递给 ctexbook。
		其中可能最常用的选项是 \verb|GBK| 和 \verb|UTF8|：
		它们选择源代码使用的字符编码，默认使用 \verb|GBK|。
\end{itemize}

例如，如果须要使用 UTF-8 编码撰写论文，
则应在载入 pkuthss 文档类时加上 \verb|UTF8| 选项：
\begin{Verbatim}
\documentclass[UTF8, ...]{pkuthss} % “...”代表其它的选项。
\end{Verbatim}

又例如，文档默认情况下是双面模式，每章都从右页（奇数页）开始。
如果希望改成一章可以从任意页开始，可以这样设置：
\begin{Verbatim}
\documentclass[openany, ...]{pkuthss} % 每章从任意页开始。
\end{Verbatim}

\section{pkuthss 文档类提供的命令和环境}
\subsection{设定文档信息的命令}\label{ssec:set-cmd}

这一类命令的语法为
\begin{Verbatim}
\commandname{具体信息} % commandname 为具体命令的名称。
\end{Verbatim}

这些命令总结如下：
\begin{itemize}
	\item \texttt{\bfseries\string\ctitle}：设定论文中文标题\footnote{%
		因为 pkuthss 内部实现机制的缘故，\myemph{双盲版论文的（中文和西文）
		标题如须强制换行，必须使用 pkuthss 提供的 \texttt{\string\thssnl}
		命令而非 \texttt{\string\\}}，否则会出错。%
	}；
	\item \texttt{\bfseries\string\etitle}：设定论文西文标题；
	\item \texttt{\bfseries\string\cauthor}：设定作者的中文名；
	\item \texttt{\bfseries\string\eauthor}：设定作者的西文名；
	\item \texttt{\bfseries\string\date}：设定日期；
	\item \texttt{\bfseries\string\studentid}：设定作者的学号；
	\item \texttt{\bfseries\string\school}：设定作者的学院名；
	\item \texttt{\bfseries\string\cmajor}：设定作者专业（二级学科）的中文名；
	\item \texttt{\bfseries\string\emajor}：设定作者专业（二级学科）的西文名；
	\item \texttt{\bfseries\string\direction}：设定作者的研究方向；
	\item \texttt{\bfseries\string\cmentor}：设定导师的中文名；
	\item \texttt{\bfseries\string\ementor}：设定导师的西文名；
	\item \texttt{\bfseries\string\ckeywords}：设定中文关键词；
	\item \texttt{\bfseries\string\ekeywords}：设定西文关键词；
	\item \texttt{\bfseries\string\degreetype}：
		设定学位类型（1 为学术学位，2 为专业学位，设为 0 则不显示学位类型）；
	\item \texttt{\bfseries\string\blindid}：设定论文编号（双盲评审用）；
	\item \texttt{\bfseries\string\discipline}：设定一级学科（双盲评审用）。
\end{itemize}
排版双盲版论文时除了要去掉致谢等章节、隐去论文中其它可能泄露个人信息的部分外，
还应注意在排版封面时须使用 \verb|\makeblind| 而非 \verb|\maketitle| 命令。

例如，如果要设定专业为“化学”（“Chemistry”），则可以使用以下命令：
\begin{Verbatim}
\cmajor{化学}
\emajor{Chemistry}
\end{Verbatim}

\subsection{自身存储文档信息的命令}

这一类命令的语法为
\begin{Verbatim}
% commandname 为具体的命令名。
\renewcommand{\commandname}{具体信息}
\end{Verbatim}

这些命令总结如下：
\begin{itemize}
	\item \texttt{\bfseries\string\cuniversity}：大学的中文名。
	\item \texttt{\bfseries\string\euniversity}：大学的西文名。
	\item \texttt{\bfseries\string\cthesisname}：论文类别的中文名。
	\item \texttt{\bfseries\string\ethesisname}：论文类别的西文名。
	\item \texttt{\bfseries\string\thesiscover}：封面显示的论文类别\footnote{%
		出于兼容性的考虑，如果 \texttt{\string\thesiscover} 为空，
		那么封面将显示 \texttt{\string\cthesisname}。%
	}。
	\item \texttt{\bfseries\string\mentorlines}：封面“导师”部分的行数。
	\item \texttt{\bfseries\string\cabstractname}：摘要的中文标题。
	\item \texttt{\bfseries\string\eabstractname}：摘要的西文标题。
\end{itemize}

例如，如果要设定论文的类别为“博士学位论文”（“Doctor Thesis”），
但封面要显示“博士研究生学位论文”，则可以使用以下命令：
\begin{Verbatim}
\renewcommand{\cthesisname}{博士学位论文}
\renewcommand{\ethesisname}{Doctor Thesis}
\renewcommand{\thesiscover}{博士研究生学位论文}
\end{Verbatim}

\subsection{以“key = value”格式设置文档信息}

用户可以通过 \verb|\pkuthssinfo| 命令集中设定文档信息，其语法为：
\begin{Verbatim}
% key1、key2、value1、value2 等为具体文档信息的项目名和内容。
\pkuthssinfo{key1 = value1, key2 = value2, ...}
\end{Verbatim}
其中文档信息的项目名为前面提到的设定文档信息的命令名
或自身存储文档信息的命令名（不带反斜杠）。

当文档信息的内容包含了逗号等有干扰的字符时，
可以用大括号将这一项文档信息的全部内容括起来。\myemph{%
	我们建议用户总用大括号将文档信息的内容括起来，
	以避免很多不必要的麻烦。%
}

例如，前面提到的文档信息的设置可以集中地写成：
\begin{Verbatim}
\pkuthssinfo{
	..., % “...”代表其它的设定。
	cthesisname = {本科生毕业论文},
	ethesisname = {Undergraduate Thesis},
	cmajor = {化学}, emajor = {Chemistry}
}
\end{Verbatim}

\subsection{其它命令和环境}\label{ssec:misc}

\texttt{\bfseries cabstract} 和 \texttt{\bfseries eabstract} 环境用于编写
中西文摘要；\texttt{\bfseries beabstract} 环境用于编写双盲评审版的西文摘要。
用户只须要写摘要的正文；标题、作者、导师、专业等部分会自动生成。

\texttt{\bfseries\string\specialchap} 命令
用于开始不进行标号但计入目录的一章，
并合理安排其页眉。\myemph{%
	注意：须要启用 \texttt{spechap} 选项才能使用此命令。
	另外，在此章内的节或小节等命令应使用带星号的版本，
	例如 \texttt{\string\section\string*} 等，
	以免造成章节编号混乱。%
}%
例如，本文档中的“序言”一章就是用 \verb|\specialchap{序言}|
这条命令开始的。%

\texttt{\bfseries\string\setpdfproperties} 命令
用于根据用户设定的文档信息自动设定生成的 pdf 文档的属性。
此命令会在用户调用 \verb|\maketitle| 命令时被自动调用，
因此通常不需要用户自己使用；
但用户有时可能不须要输出封面，从而不会调用 \verb|\maketitle| 命令，
此时就须要在设定完文档信息之后调用 \verb|\setpdfproperties|。%
\myemph{注意：须要启用 \texttt{pdfprop} 选项才能使用此命令。}

\texttt{\bfseries\string\thssnl} 命令用于在双盲版论文的（中文和西文）标题中
强制换行，见第 \ref{ssec:set-cmd} 小节中关于 \verb|\ctitle| 说明的脚注。

\section{从其它文档类和宏包继承的功能}\label{sec:thirdparty}

pkuthss 文档类建立在 ctexbook\cupercite{ctex} 文档类之上，
并调用了 geometry\cupercite{geometry}、fancyhdr\cupercite{fancyhdr}、%
hyperref\cupercite{hyperref}、graphicx\cupercite{graphicx}
和 ulem\cupercite{ulem} 等几个宏包。
因此，ctexbook 文档类和这些宏包所提供的功能均可以使用。

例如，用户如果想将目录的标题改为“目{\quad\quad}录”，
则可以使用 ctexbook 文档类提供的 \verb|\ctexset| 命令：
\begin{Verbatim}
\ctexset[contentsname = {目{\quad\quad}录}]
\end{Verbatim}

在默认的配置下，%
pkuthss 文档模版使用作者编写的 biblatex\cupercite{biblatex} 样式%
\cupercite{biblatex-caspervector}进行参考文献和引用的排版，
用户可以使用它以及 biblatex 本身所提供的功能。
例如，用户可以分别使用 \verb|\cite|、\verb|\parencite| 和 \verb|\supercite|
生成未格式化的、带方括号的和上标且带方括号的引用标记：
\begin{Verbatim}
\cite{ctex}，\parencite{ctex}，\supercite{ctex}
\end{Verbatim}
在本文中将产生“\cite{ctex}，\parencite{ctex}，\supercite{ctex}”。

就目前而言，在 biblatex 中，通过更复杂的设置，
还可以满足例如被引用的文献按照引用顺序排序，
而未引用的文献按照西文文献在前、中文文献在后排序这样的需求，
详见 biblatex-caspervector 的文档\cupercite{biblatex-caspervector}。

除此之外，pkuthss 文档类还可能调用以下这些宏包：
\begin{itemize}
	\item 启用 \verb|pkufont| 选项时会调用 unicode-math
		\cupercite{unicode-math} 宏包（\hologo{XeLaTeX} 编译）或
		mathptmx/helvet\cupercite{psnfss} 和 textcomp 宏包（非
		\hologo{XeLaTeX} 编译），此外在非 \hologo{XeLaTeX} 编译或不启用
		\verb|pkufont| 选项时均会调用 amssymb\cupercite{amssymb} 宏包。
	\item 启用 \verb|pkufoot| 选项时会调用
		tikz\cupercite{tikz} 和 scrextend\cupercite{scrextend} 宏包。
	\item 启用 \verb|pkuspace| 选项时会调用
		tocloft\cupercite{tocloft}、caption\cupercite{caption} 和
		subcaption\cupercite{subcaption} 宏包。
	\item 启用 \verb|spacing| 选项时会调用 setspace 和
		enumitem\cupercite{enumitem} 宏包。
\end{itemize}
因此在启用相应选项时，用户可以使用对应宏包所提供的功能。

\section{高级设置}\label{sec:advanced}

pkuthss 文档模版的实现是简洁、清晰、灵活的。
当一些细节的自定义无法通过模版提供的外部接口实现时，
我们鼓励用户（在适当理解相关部分代码的前提下）
通过修改 pkuthss 文档类的源文件进行自定义。
在目前常用的 \hologo{TeX} 系统中，
假设 pkuthss 的说明文档所在目录具有下述形式的路径：
\begin{Verbatim}
# 说明文档所在目录（$TEXMFDIST 的形式见下面几行）：
$TEXMFDIST/doc/latex/pkuthss/
# 若用户使用 Windows 下的 TeX Live 系统，则 $TEXMFDIST 一般类似于：
C:\texlive\2015\texmf-dist
# 若用户使用类 Unix 下的 TeX Live 系统，则 $TEXMFDIST 一般类似于：
/usr/local/texlive/2015/texmf-dist
\end{Verbatim}
则其源文件所在目录应该位于以下目录：
\begin{Verbatim}
$TEXMFDIST/tex/latex/pkuthss/
\end{Verbatim}

如果的确须要修改 pkuthss 文档类的源文件，\myemph{%
	建议用户将 \texttt{pkuthss.cls} 或其它须要修改的文件
	复制到被编译的主文件所在的目录，
	然后对此副本进行修改%
}\footnote{%
	能这样做的原因是目前常用的 \hologo{TeX} 系统在读取编译用到的文件时，
	会优先考虑工作目录（即主文件所在目录）中的文件。%
}。这样做的目的主要是使用户不必在每次调整文档类文件时都去上述路径修改；
同时这样也可以在（万一须要）更新 \hologo{TeX} 系统时，
防止用户修改过的文档类文件在更新中被自动覆盖掉。

一个常见的需求是封面中部分内容（特别是论文的标题、专业和研究方向）太长，
超出了在预设的空间。
此时，用户可以修改 \verb|pkuthss.cls| 里 \verb|\maketitle| 定义中
\verb|\thss@int@fillinblank| 宏的参数来改变带下划线的空白的行数和行宽，
具体方法可以参考该文件中和 \verb|\mentorlines| 相关的代码。

% vim:ts=4:sw=4