Merge pull request #242 from BITNP/grad-guides

针对研究生院官网发布而添加的快速使用手册

.gitignore

@@ -294,3 +294,5 @@ scripts/*
 !scripts/*.ps1
 
 .DS_Store
+
+BIT-bithesis-graduates*

Makefile

@@ -55,6 +55,7 @@ test: doc copy FORCE_MAKE
 	cd $(SCAFFOLDDIR)/presentation-slide && latexmk && cd ..
 	cd $(TESTDIR)/doctor-thesis && latexmk && cd ..
 	cd $(TESTDIR)/autorefs && latexmk && cd ..
+	cd ./the-graduates-handbook && latexmk && cd ..
 
 regression-test: cls
 	$(REGRESSION_TEST_COMMAND)
@@ -67,6 +68,7 @@ copy: cls
 	cp bithesis.cls $(SCAFFOLDDIR)/reading-report
 	cp bithesis.cls $(TESTDIR)/doctor-thesis
 	cp bithesis.cls $(TESTDIR)/autorefs
+	cp bithesis.cls ./the-graduates-handbook
 	cp bitreport.cls $(SCAFFOLDDIR)/lab-report
 	cp bitbeamer.cls $(SCAFFOLDDIR)/presentation-slide
 
@@ -99,6 +101,23 @@ pkg: doc
 	mv ./bithesis/README-bithesis.md ./bithesis/README.md
 	zip -r bithesis.zip bithesis
 
+GRAD_DEST_DIR = ./BIT-bithesis-graduates
+
+grad: doc copy FORCE_MAKE
+	# if $version is not specified, alert the user.
+	@if [ -z "$$version" ]; then \
+		echo -e "\e[32mPlease specify the version of the template you want to generate.\e[0m"; \
+		echo -e "\e[32mFor example: make grad version=1.0.0\e[0m"; \
+		exit 1; \
+	fi
+	cd ./the-graduates-handbook && latexmk && cd -
+	cd $(SCAFFOLDDIR)/graduate-thesis && latexmk && latexmk -c && cd -
+	cp -r $(SCAFFOLDDIR)/graduate-thesis ${GRAD_DEST_DIR}-${version}
+	cp ./bithesis.pdf ${GRAD_DEST_DIR}-${version}/
+	cp ./the-graduates-handbook/main.pdf ${GRAD_DEST_DIR}-${version}/'研究生学位论文模板快速使用手册'.pdf
+	zip -r ${GRAD_DEST_DIR}-${version}.zip ${GRAD_DEST_DIR}-${version}
+
+
 examples: cls
 	cp bithesis.cls $(EXAMPLEDIR)/cover/
 	cp bithesis.cls $(EXAMPLEDIR)/publications/

_typos.toml

@@ -2,6 +2,9 @@
 ist = "ist"
 acn = "acn"
 usera = "usera"
+multline = "multline"
+Winn = "Winn"
+nd = "nd"
 
 [files]
-extend-exclude = ["CHANGELOG.md"]
+extend-exclude = ["CHANGELOG.md", "main.bib"]

the-graduates-handbook/chapters/acknowledgements.tex

@@ -0,0 +1,11 @@
+\begin{acknowledgements}
+
+感谢研究生院对本项目的大力支持。
+特别感谢杨雅婷老师在对原有模板的大量贡献，为推动本模板官方化付出的精力。
+
+感谢所有对本模板更新与维护做出贡献的同学和老师们，他们的名字可以在\href{https://github.com/BITNP/BIThesis/graphs/contributors}{GitHub
+  Contributors} 上看到。同时， 也由衷感谢在 \href{https://github.com/BITNP/BIThesis/issues?q=}{GitHub}
+对该项目上提出大量珍贵修改意见的老师和同学们。
+
+
+\end{acknowledgements}

the-graduates-handbook/chapters/appendices.tex

@@ -0,0 +1,51 @@
+\begin{appendices}
+\label{resources}
+  \chapter{学习资料}
+
+  \section{\LaTeX 学习资料推荐}
+  \begin{itemize}[nosep]
+    \item \href{https://www.overleaf.com/learn/latex/Tutorials}{《Overleaf 在线文档》（英文）} 提供了非常好的在线学习资源。
+    \item \href{https://texdoc.org/serve/lshort-zh-cn.pdf/0}{《一份（不太）简短的 LATEX 2ε 介绍》} 可以作为更详尽的语法手册。
+  \end{itemize}
+
+  \section{\BIThesis 模板配置使用手册}
+  \BIThesis{} 使用手册位于项目文件夹的 \verb|./bithesis.pdf|。它包括了关于 \BIThesis{} 的详细使用说明，
+      对于每一个配置选项都有详细的说明和示例。
+
+  \chapter{\BIThesis 与北理工历代\LaTeX{}模板项目简介}
+
+\begin{itemize}[nosep]
+  \item 在 2017 年之前，网络上已经出现一些北京理工大学学位论文 \LaTeX 模板。
+    它们是“2012大眼小蚂蚁版”和“2016汪卫版”，均以上海交通大学的模板为基础。
+  \item 2017 - 2018 年，计算机学院 2016 级研究生杨雅婷等人受研究生院委托，
+    制作了\href{https://github.com/BIT-thesis/LaTeX-template}{BIT-Thesis} 
+    研究生学位论文模板。
+  \item 2019 - 2020 年，\BIThesis 最早由 2016 级的
+    武上博、王赞、唐誉铭、牟思睿和詹熠莎等人维护。
+    \begin{itemize}[nosep]
+    \item 此时，\BIThesis 仅支持本科生毕业论文的排版。
+    \item 在此期间，\BIThesis 从无到有诞生了，包括使用手册、
+      在线文档和开箱即用的模板。
+    \item 同时，2017 级的赵池等同学完成了一系列 \BIThesis 
+      的视频教程。
+    \item 武上博推进了教务部对 \BIThesis{} 的认可工作。
+  \end{itemize}
+  \item 2020 - 2021 年，2017 级的冯开宇、杨思云、郝正亮和顾骁等人
+      接管了维护开发工作。
+  \begin{itemize}[nosep]
+    \item 在此期间，冯开宇将原来的 .tex 文件制作成了宏包，并发布到 CTAN 上。
+    \item 此版本是 V2 版本，代号为 Birthday Cake.
+  \end{itemize}
+  \item 2021 - 2022 年，2021 级（硕士研究生）的冯开宇针对 2021、
+      2022 毕业季收到的反馈对该项目进行维护升级。
+  \begin{itemize}[nosep]
+    \item 在此期间，冯开宇合入了杨雅婷等人在 2017 年开发的研究生学位论文模板。
+    \item 次年暑假期间，冯开宇用 \verb|expl3| 重构了\LaTeX 样式代码，
+      向用户提供了简易易用的接口。同时，也增加了本科全英文专业的毕设论文模板样式。
+    \item 此版本是 V3 版本，代号为 Summer Time.
+  \end{itemize}
+  \item 2023 年，冯开宇在此版本上增加了多种新的功能，并修复了一些已知的问题。
+  并推进了官方（教务部、研究生院）对 \BIThesis 的认可工作。
+\end{itemize}
+
+\end{appendices}

the-graduates-handbook/chapters/ch0-quick-start.tex

@@ -0,0 +1,122 @@
+\chapter{快速使用指南}
+\label{ch:quick-start}
+
+\textbf{本章将通过多个小节，介绍如何快速
+成功编译出一份符合学校要求的毕业论文。}
+
+其中，第\ref{sec:local-compile}节介绍在本地电脑上编译生成 PDF；
+第\ref{sec:overleaf-compile}节介绍在 Overleaf（浏览器）上编译生成 PDF。这两种方法相互独立，你可以根据喜好自行选择其中一种。
+
+\section{方法一：在本地电脑上编译生成 PDF}
+\label{sec:local-compile}
+
+\subsection{安装 TeX 发行版——TeX Live}
+
+访问 \url{https://www.tug.org/texlive/}，下载并安装 TeX Live。TeX Live 包含了所有将 \LaTeX 编译成 PDF 所需的代码和工具。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/local-texlive-download.png}
+  \end{center}
+  \caption{TeX Live 下载页面}
+  \label{fig:local-texlive-download}
+\end{figure}
+
+\subsection{安装编辑器——TeXstudio}
+
+访问 \url{https://www.texstudio.org/}，下载并安装 TeXstudio。TeXstudio 是一个开源的、跨平台的、功能强大的 \LaTeX 编辑器。使用它，你可以更方便地进行 \LaTeX 的写作与编辑。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/texstudio-overview.png}
+  \end{center}
+  \caption{TeXstudio 界面}
+  \label{fig:texstudio-overview}
+\end{figure}
+
+\subsection{下载模板}
+
+\textit{如果你选择使用目前版本的模板，可以跳过该步骤。}
+
+访问 \url{https://bithesis.bitnp.net}，点击右上角的 ``模板下载'' ，跳转到 \BIThesis 项目的 GitHub Releases 页面（也即 \url{https://github.com/BITNP/BIThesis/releases/latest}）。选择``graduate-thesis.zip''的模板压缩包并下载。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/github-releases.png}
+  \end{center}
+  \caption{模板下载页面}
+  \label{fig:local-template-download}
+\end{figure}
+
+\subsection{编译生成 PDF}
+
+解压模板压缩包，打开 TeXstudio，点击 ``File > Open'' 按钮，选择 ``main.tex'' 文件，即可打开模板。
+
+接着，点击 ``Build \& View'' 按钮（两个叠加的绿色三角），即可编译生成 PDF。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/texstudio-compile-and-view.png}
+  \end{center}
+  \caption{TeXstudio 编译生成 PDF}
+  \label{fig:texstudio-compile-and-view}
+\end{figure}
+
+\section{方法二：在 Overleaf（浏览器）上编译生成 PDF}
+\label{sec:overleaf-compile}
+
+\BIThesis 项目已经在 Overleaf 上分享了多个模板，它们
+会与最新版本保持同步\footnote{需要注意，你复制的模板不会自动更新。}。
+因此，你可以直接在 Overleaf 上复制并使用这些模板。
+
+\subsection{注册 Overleaf 账号}
+
+访问 \url{https://overleaf.com}（如图\ref{fig:overleaf-register}所示），点击右上角的 ``Register'' 按钮，注册账号并登录。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/overleaf-register.png}
+  \end{center}
+  \caption{Overleaf 注册页面}
+  \label{fig:overleaf-register}
+\end{figure}
+
+
+\subsection{访问 \BIThesis 的 Overleaf 模板}
+
+访问 \url{https://bithesis.bitnp.net}，点击右上角的 ``Overleaf'' ，即可跳转到模板页面。
+
+选择``研究生学位论文模板'' 模板，点击 ``Open in Overleaf'' 按钮，即可跳转到 Overleaf 上分享的项目中。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/overleaf-choose-template.png}
+  \end{center}
+  \caption{在 BIThesis-wiki 中，选择合适的模板并跳转}
+  \label{fig:overleaf-template}
+\end{figure}
+
+\subsection{复制模板到自己的新项目中}
+
+点击左上角的 ``Menu'' 按钮，选择 ``Copy Project''，即可复制模板到自己的新项目中。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/overleaf-copy-project.png}
+  \end{center}
+  \caption{复制模板到自己的新项目中}
+  \label{fig:overleaf-copy-project}
+\end{figure}
+
+\subsection{编译生成 PDF}
+
+点击 ``Recompile'' 按钮，即可编译生成 PDF。
+
+\begin{figure}[H]
+  \begin{center}
+    \includegraphics[width=0.85\textwidth]{imgs/overleaf-compile.png}
+  \end{center}
+  \caption{编译生成 PDF}
+  \label{fig:overleaf-recompile}
+\end{figure}
+

the-graduates-handbook/chapters/ch1-intro.tex

@@ -0,0 +1,111 @@
+\chapter{关于 \LaTeX 和 \BIThesis 的一些疑难解答}
+\label{chap:what}
+
+\section{为什么要用 \LaTeX{} 和 \BIThesis{}？}
+
+学术、学位论文有严格的格式要求。为了更多同学的方便使用，校方一般提供大家更为熟悉
+的 Word 模板。虽然 Word 确实是大家最常用的排版工具，但是：
+\begin{center}
+  \kaishu
+  如果你有足够多使用 Word 的经历，一定会体验过「同一份 Word 文档，在不同地方打开
+  就变得不同」这样的魔幻现实主义色彩的经历。
+\end{center}
+
+\LaTeX{} 是专用于高质量的学术论文排版的排版工具，能让同学们更专注于内容本身，更
+自信地排版符合格式要求的学术、学位论文。\BIThesis{} 项目旨在提供一套开箱即用的、
+符合北京理工大学硕士（博士）学位论文的\LaTeX{} 模板，以助力高质量的学术写作。通
+过 \BIThesis{} 模板，学生可以轻松撰写符合学校格式要求的学位论文，可避免繁琐的论
+文格式调整，从而将关注点更多地放在高质量的内容本身。
+
+\section{为何需要这么多步骤，我该如何开始？}
+
+首先，\LaTeX{} 并不是像 Word 一样的一个开箱即用的软件。\LaTeX{} 本质上是一门用于
+排版的「语言」或「语法规则」。我们实际上，是以 \underline{纯文本文件}（以
+\texttt{.tex} 结尾的文件）为基础，用这样的一套 \underline{拟定好的标记语法} 来
+设定文字的格式，并 \underline{利用一些工具}，将其转化为符合格式要求的 PDF 文档。
+
+我们重新回顾一下这句话：
+
+\begin{itemize}[noitemsep]
+  \item \textbf{\underline{纯文本文件}} 意味着我们只需要创建一个以 \texttt{.tex}
+  结尾的文件，即可开始论文内容的撰写；
+  \item \textbf{\underline{拟定好的语法}} 则需要我们了解一些 \LaTeX{} 中常用的语
+  法语言规则，用来以纯文本的形式描述内容的格式，从而让下面提到的工具可以根据格式
+  需要，将文档转化为PDF。
+  \item \textbf{\underline{利用一些工具}} 也就表示我们需要这些工具（程序），来将
+  纯文本内容转化为符合格式的 PDF 文档：我们或是下载安装他们到本地，或是使用在线
+  平台开箱即用；
+\end{itemize}
+
+因此，本手册也将以这样的逻辑，为大家分别介绍每处需要的知识 --- 我们将首先介绍如
+何「安装这些工具」，并如何更舒服的创建、编写此「纯文本文件」（在自己的电脑上和使
+用在线的编辑器是不一样的）；而后，我们将在后续的章节，简单的讲述常用的「拟定好的
+语法」--- 以让大家快速上手，使用 \BIThesis{} 撰写自己的毕业论文。
+
+\section{在自己的电脑上编写论文}
+
+在这里，我们将在自己的电脑上配置安装撰写 \LaTeX{} 的相关工具。首先，我们搞定
+\underline{一些工具} 的安装，来更方便的撰写 \underline{纯文本文件} 并将其转化为
+符合格式的 PDF 文档。
+
+\paragraph{一些工具的安装} 在 \LaTeX{} 的世界中，我们的「一些工具」包括将
+\LaTeX{} 源码按照格式转换为 PDF 文档的「编译器」，和支撑部分 \LaTeX{} 格式语法的
+「宏包」。我们将他们统称为一个 \LaTeX{} 发行版 --- 也就是我们需要在自己的电脑上
+安装的软件。
+
+根据同学们使用的操作系统，可以安装相应的 \LaTeX{} 发行版：
+
+\begin{itemize}[noitemsep]
+  \item \textbf{Windows 或 Linux}：下载安装 \TeX{}Live。以 Windows 为例，访问
+  \href{https://www.tug.org/texlive/windows.html}{TeX Live on Windows - Easy
+  install}，并下载运行 \texttt{install-tl-windows.exe}；
+  \item \textbf{macOS}：下载安装 Mac\TeX{}，即访问
+  \href{https://www.tug.org/mactex/mactex-download.html}{MacTeX - Downloading
+  MacTeX 2022} 并下载安装 \texttt{MacTeX.pkg}；
+\end{itemize}
+
+\paragraph{纯文本文件} 我们撰写的 \LaTeX{} 文档，确实是「无格式」的纯文本文档。
+也因此，任何能够编辑纯文本的工具我们其实都可以使用。但是，专业的\LaTeX{} 编辑器
+一般会提供 \LaTeX{} 源码的编辑和预览功能。虽然不是必要的，但是使用编辑器可以大大
+提高\LaTeX{} 的使用效率。
+
+对于 \TeX{}Live 或者 Mac\TeX，发行版自带了基础的编辑器（分别是 \TeX{}works 和
+\TeX{}Shop），可直接使用。集成的编辑环境，比如 \TeX{}studio 也是推荐大家使用的。
+另外，比如 VS Code 和 Vim 等通用代码编辑器，也可以借助插件的安装，提升 \LaTeX{}
+的撰写体验。
+
+到此，我们其实就可以直接使用本模板，在自己的电脑上进行论文的编写了。如果想再了解
+有关在线编辑平台 Overleaf 的相关内容，请继续阅读~\ref{sec:online-overleaf} 节；
+否则，大家可以直接跳转到~\ref{sec:using-bithesis} 节，了解模板的使用方法。
+
+\section{本地编辑或是 Overleaf 在线平台，我改使用哪一个？}
+\label{sec:online-overleaf}
+
+Overleaf 是一个在线的 \LaTeX{} 编辑器，可以直接在网页上进行 \LaTeX{} 的编辑和预
+览。大家可以访问注册 \url{https://overleaf.com} 使用 Overleaf 在线编写
+\LaTeX{}。选用 Overleaf 有优点也有缺点：
+\begin{itemize}[noitemsep]
+  \item 优点在于：
+    \begin{itemize}[noitemsep]
+      \item 不需要安装 \LaTeX{} 发行版，不需要配置编辑器，直接在网页上进行
+      \LaTeX{} 的编辑和预览。
+      \item 数据保存在云端，可以在多个设备上进行编辑和预览。
+      \item 可以共享项目，方便多人协作。（对于毕业论文来说，这个优点并不是很重
+      要。）
+    \end{itemize}
+  \item 缺点在于：
+    \begin{itemize}[noitemsep]
+      \item 由于 Overleaf 是一个在线的编辑器，所以需要保持网络连接，否则无法进行
+      编辑和预览。
+      \item 很多同学使用了第三方的文献管理软件，如 Zotero。Overleaf 无法直接与这
+      些软件进行集成，需要手动导入文献。
+      \item 网页版的编辑器功能有限，无法进行复杂的自定义配置。
+    \end{itemize}
+\end{itemize}
+
+因此，需要使用者根据自己的需求进行选择。此外，我们的模板上传到 Overleaf 以后，需
+要修改项目配置才能正常编译：
+\begin{enumerate}[noitemsep]
+  \item 选择左上角 \texttt{Menu} 以打开侧边栏。
+  \item 修改 \texttt{Settings} 中 \texttt{Compiler} 一项的值为 \texttt{XeLaTeX}（默认为 \texttt{pdfLaTeX}）。
+\end{enumerate}