chore: 更新开发文档、脚本等资料

- 文档

  - 调整章节顺序
  - 强调`make copy`
  - 指出`make doc`的结果是`bithesis.pdf`
  - MacOS → macOS
  - 改进 Windows 开发指引，原先有错误，例如 Git Bash 其实并不提供 GNU make

- `.gitignore`

  - 删除重复的`templates/.gitignore`
  - 忽略 markdown 宏包生成的 lua bridge (#470)

- `Makefile`

  - 删除无用的 `$LATEX`
  - 补全`.PHONY`
  - `latexmk -c && latexmk` → `latexmk -gg`，这样更清楚
  - `bash` → `sh`，这样更通用

- `the-graduates-handbook/` → `handbook/`，因为本科、硕博都是这里，并非仅仅“graduate”

- [check-shebang-scripts-are-executable](https://github.com/pre-commit/pre-commit-hooks/tree/main?tab=readme-ov-file#check-shebang-scripts-are-executable)

Author: YDX-2147483647

.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: handbooks
-          path: "the-graduates-handbook/*.pdf"
+          path: "handbook/*.pdf"
       - name: Upload *.cls for later usage.
         uses: actions/upload-artifact@v4
         with:
@@ -170,18 +170,18 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: handbooks
-          path: the-graduates-handbook
+          path: handbook
       - name: Upload undergraduate-handbook
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: the-graduates-handbook/undergraduate-handbook.pdf
+          file: handbook/undergraduate-handbook.pdf
           tag: ${{ github.ref }}
       - name: Upload graduate-handbook
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: the-graduates-handbook/graduate-handbook.pdf
+          file: handbook/graduate-handbook.pdf
           tag: ${{ github.ref }}
 
   upload_to_ctan:

.gitignore

@@ -15,6 +15,7 @@
 *.pdf
 *.hd
 *.sty
+*.luabridge.lua
 
 ## Intermediate documents:
 *.dvi

DEVELOPMENT.md

@@ -1,70 +1,76 @@
 # 开发者指南
 
-## 任务管理
+> [!TIP]
+>
+> 本项目采用 [GitHub Projects](https://github.com/BITNP/BIThesis/projects) 进行任务管理。
+> 你可以每次选择其中的一个小的 TODO 进行开发；来帮助项目一点一点前进。
 
-本项目采用 [GitHub Projects](https://github.com/BITNP/BIThesis/projects) 进行任务管理。
-你可以每次选择其中的一个小的 TODO 进行开发；来帮助项目一点一点前进。
+## 本地开发
 
-## 开发命令
+一般开发需求分为三种：
 
-Makefile 主要针对 Linux 和 MacOS 开发者；如果你使用 Windows 开发，可以使用 Git Bash 或 Cygwin，不过偶尔可能需要手动执行 Makefile 中具体的命令。
+- 修改 `templates/` 中某个模板
 
-当然，也欢迎你贡献更通用的开发脚本。
+  例：改进`ref.bib`中的示例，在 `main.tex` 中补充注释。
 
-### 生成 `.cls` 文件
+- 修改 `bithesis.dtx` 文件
 
-```Bash
-make cls
-```
+  例：添加新命令，更改 `\BITSetup` 选项。
 
-### 生成宏包手册
+- 修改其他文件。
 
-```Bash
-make doc
-```
+> [!TIP]
+>
+> Windows 开发者若运行 Makefile 遇到问题，请参考[后文](#Windows)。
 
-### 本地开发
+### 修改 `templates/` 中某个模板
 
-一般开发需求分为三个部分：
+如果改动仅仅涉及某个模板，那么相对简单一些：
 
-- 修改 `bithesis.dtx` 文件。
-- 修改 `templates/` 中某个模板。
-- 修改其他文件。
+1. 初次开发前，运行 `make copy`，这会生成 `*.cls` 并更新到 `templates/` 下。
+2. 编辑模板。
+3. 测试，确保你的改动能够正确编译；并且不会影响到其他效果。
 
-#### bithesis.dtx 开发流程
+### 修改 `bithesis.dtx` 文件
 
-1. 如果需求涉及到添加新的命令，可以先在 `templates/` 中进行具体的实现。
-2. 然后，将实现的代码拷贝到 `bithesis.dtx`。
-3. 然后运行 `make copy` 将新的 `*.cls` 更新到 `templates/` 下。
-4. 不要忘记更新 `bithesis.dtx` 中的手册部分，添加相应说明。
-5. 运行 `make doc` 编译手册。
-6. 运行测试，确保你的改动不会影响到其他功能。
+1. 编辑 `bithesis.dtx`。
+2. 运行 `make copy`，这会生成新的 `*.cls` 并更新到 `templates/` 下。
+3. 更新文档（`bithesis-doc.tex` 以及 `bithesis.dtx` 中的注释），然后运行 `make doc` 编译出手册`bithesis.pdf`。
+4. 测试，确保你的改动不会影响到其他功能。
 
-#### 修改 `templates/` 中模板的行为
+> [!TIP]
+>
+> 如果要添加新命令，可以先在 `templates/` 中具体实现，再拷贝到 `bithesis.dtx`。
 
-如果改动仅仅涉及某个模板，那么相对简单一些：
+## 参考资料
+
+- 本项目采用 LaTeX3，可以参考 [LaTeX3: Programming in LaTeX with Ease](https://www.alanshawn.com/tech/2020/10/04/latex3-tutorial.html)、[expl3 的文档](https://www.latex-project.org/help/documentation/)等。
+- 关于模板，[fduthesis 项目代码](https://github.com/stone-zeng/fduthesis)有很多最佳实践，可以参考。
+- 样式部分则应参考[研究生院](https://grd.bit.edu.cn/xwgz/xwgz2/wjxz_xwgz/)和教务部的相关文件和通知。
 
-1. 直接修改模板中的样式
-2. 进行测试，确保你的改动能够正确编译；并且不会影响到其他效果。
+## Makefile 的进一步介绍
 
-#### 辅助命令
+### Windows
 
-由于我们常常需要实时预览代码编译的效果，而 LaTeX 本身没有提供实时编译的功能。
-因此我们常常需要来回运行 `make copy`、`latexmk` 以达成实时编译的效果。
+Makefile 主要针对 Linux 和 macOS 开发者；Windows 开发者要确保至少有：
 
-因此 Makefile 里面提供了一些辅助开发的命令（以 `dev-`）开头。
-可以帮助你自动化以上流程。
+- GNU make——可按 [ScoopInstaller/Main: `make.json`](https://github.com/ScoopInstaller/Main/blob/master/bucket/make.json) 中的 `url` 下载。
+- GNU coreutils——可使用内置了 coreutils 的 Git Bash 或 Cygwin，或者[安装 uutils-coreutils](https://uutils.github.io/coreutils/docs/installation.html#windows)。
+
+当然，也欢迎你贡献更通用的开发脚本。
+
+### 辅助命令
+
+我们常常需要实时预览代码编译的效果，而 LaTeX 本身没有提供实时编译的功能，导致我们要来回运行 `make copy`、`latexmk`。
+
+为此 Makefile 提供了一些辅助命令，以 `dev-`开头，可以帮助你自动化以上流程。
 
 或者你可以使用类似 `rg --files | entr make copy` 以及 `rg --files | entr latexmk` 来达到
 「代码修改后立即重新编译」的效果。
 
-## 参考资料
-
-- 本项目 LaTeX3，因此可以参考的手册包括 [expl3 的文档](https://www.latex-project.org/help/documentation/)。
-- [fduthesis 项目代码](https://github.com/stone-zeng/fduthesis)有很多最佳实践，可以参考。
-- 样式部分，应该参考研究生院和教务部的相关文件和通知。
+（这些命令未必适用于 Windows，可能要手动用 [watchexec](https://watchexec.github.io/) 等替代。）
 
-## 单元测试和回归测试
+### 单元测试和回归测试
 
 运行 `make test` 将对所有的模板进行编译测试（同样被用于 GitHub Actions）。
 
@@ -75,13 +81,13 @@ make doc
 - [diff-pdf](https://vslavik.github.io/diff-pdf/)
 - [jq](https://jqlang.github.io/jq/)（仅用 Zsh 时需要）
 
-## 打包
+### 打包
 
 - `make overleaf version=X.X.X` 可以生成上传 overleaf 所需要的 zip 文件。
 - `make pkg` 可以生成上传 CTAN 所需要的 zip 文件。若已有手册而不想重新编译，可 `make pkg-only`。（同样被用于 GitHub Actions）
 - `make grad version=X.X.X` 可以生成用作研究生院官网附件的 zip 文件。
 
-## 上传 Overleaf 与更新
+### 上传 Overleaf 与更新
 
 > [!NOTE]
 > Overleaf 链接已利用 [`overleaf.com/docs` API](https://www.overleaf.com/devs) 自动指向最新发布版，不再需要手动更新。

Makefile

@@ -1,10 +1,8 @@
-# 以下命令仅保证能在 Linux 或 MacOS 环境下执行。
+# 以下命令仅保证能在 Linux 或 macOS 环境下执行。
 # 如果你是 Windows 用户，可以使用 Git Bash 或者 Cygwin 来执行；
 # 或者可以考虑将此脚本移植为 PowerShell。
 PACKAGE = bithesis
 
-LATEX = xelatex
-
 SOURCES = $(PACKAGE).ins $(PACKAGE).dtx
 CLSFILE = dtx-style.sty bitreport.cls bithesis.cls bitbeamer.cls
 
@@ -21,30 +19,37 @@ else
 endif
 
 
-.PHONY: all cls doc clean FORCE_MAKE copy pkg pkg-only
+.PHONY: all FORCE_MAKE
 
 $(PACKAGE).pdf: cls FORCE_MAKE
 	@$(LATEXMK) -xelatex $(PACKAGE).dtx
 
 $(CLSFILE): $(SOURCES)
 	yes y | xetex $(PACKAGE).ins
 
+.PHONY: cls
 cls: $(CLSFILE)
 
+.PHONY: doc
 doc: $(PACKAGE).pdf
 
+.PHONY: viewdoc
 viewdoc: doc
 	$(LATEXMK) -pv $(PACKAGE).dtx
 
+.PHONY: clean
 clean:
 	$(LATEXMK) -c $(PACKAGE).dtx
 	-rm -rf *.glo $(CLSFILE)
 
+.PHONY: clean-dist
 clean-dist:
 	-rm -rf $(PACKAGE).pdf
 
+.PHONY: clean-all
 clean-all: clean clean-dist FORCE_MAKE
 
+.PHONY: test
 test: doc copy FORCE_MAKE
 	cd $(SCAFFOLDDIR)/undergraduate-thesis && latexmk && cd ..
 	cd $(SCAFFOLDDIR)/paper-translation && latexmk && cd ..
@@ -55,12 +60,14 @@ 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 && latexmk -c \
-		&& GRADUATE=true latexmk && cd ..
+	cd ./handbook && latexmk \
+		&& GRADUATE=true latexmk -gg && cd ..
 
+.PHONY: regression-test
 regression-test: cls
 	$(REGRESSION_TEST_COMMAND)
 
+.PHONY: copy
 copy: cls
 	cp bithesis.cls $(SCAFFOLDDIR)/undergraduate-thesis
 	cp bithesis.cls $(SCAFFOLDDIR)/undergraduate-thesis-en
@@ -69,11 +76,12 @@ 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 bithesis.cls ./handbook
 	cp bitreport.cls $(SCAFFOLDDIR)/lab-report
 	cp bitbeamer.cls $(SCAFFOLDDIR)/presentation-slide
 
 # Generate scaffolds for overleaf
+.PHONY: overleaf
 overleaf: doc FORCE_MAKE
 	# if $version is not specified, alert the user.
 	@if [ -z "$$version" ]; then \
@@ -86,33 +94,38 @@ overleaf: doc FORCE_MAKE
 	make copy
 	mkdir overleaf
 	ls templates | \
-		xargs -I {} bash -c \
+		xargs -I {} sh -c \
 		"cp -r ./templates/{} overleaf && cp $(PACKAGE).pdf ./overleaf/{} && (cd overleaf/{}/ && zip -r ../BIThesis-{}-v$(version).zip .)"
 
+.PHONY: dev
 dev:
 	ls bithesis.dtx | entr -s 'yes y | make doc && make copy'
 
+.PHONY: dev-doc
 dev-doc:
 	ls bithesis.dtx | entr -s 'make clean-all && yes y | make doc && open bithesis.pdf'
 
+.PHONY: pkg-only
 pkg-only:
 	rm -rf ./bithesis ./bithesis.zip
 	mkdir bithesis
 	cp bithesis.ins bithesis.dtx bithesis.pdf ./README*.md ./contributing*.md ./bithesis
 	mv ./bithesis/README-bithesis.md ./bithesis/README.md
 	zip -r bithesis.zip bithesis
 
+.PHONY: pkg
 pkg: doc pkg-only
 
 GRAD_DEST_DIR = ./BIThesis-graduate-thesis-template
 
+.PHONY: handbooks
 handbooks: copy FORCE_MAKE
-	cd the-graduates-handbook && latexmk -c \
-		&& GRADUATE=true latexmk && mv main.pdf graduate-handbook.pdf \
-	  && latexmk -c \
-	  && latexmk && mv main.pdf undergraduate-handbook.pdf && cd -
+	cd handbook \
+		&& GRADUATE=true latexmk -gg && mv main.pdf graduate-handbook.pdf \
+		&& latexmk -gg && mv main.pdf undergraduate-handbook.pdf && cd -
 
 # 用于提供给研究生院
+.PHONY: grad
 grad: doc copy handbooks FORCE_MAKE
 	# if $version is not specified, alert the user.
 	@if [ -z "$$version" ]; then \
@@ -125,14 +138,15 @@ grad: doc copy handbooks FORCE_MAKE
 	mkdir ${GRAD_DEST_DIR}-${version}
 	cp -r $(SCAFFOLDDIR)/graduate-thesis/ ${GRAD_DEST_DIR}-${version}/graduate-thesis/
 	cp ./bithesis.pdf ${GRAD_DEST_DIR}-${version}/'3-详细配置手册'.pdf
-	cp ./the-graduates-handbook/graduate-handbook.pdf ${GRAD_DEST_DIR}-${version}/'2-快速使用手册'.pdf
+	cp ./handbook/graduate-handbook.pdf ${GRAD_DEST_DIR}-${version}/'2-快速使用手册'.pdf
 	(cd ${GRAD_DEST_DIR}-${version}/graduate-thesis/ && zip -rm ../"1-BIThesis-论文模板-${version}".zip . )
 	rmdir ${GRAD_DEST_DIR}-${version}/graduate-thesis
 	zip -r ${GRAD_DEST_DIR}-${version}.zip ${GRAD_DEST_DIR}-${version}
 
 UNDERGRAD_DEST_DIR = ./BIThesis-undergraduate-thesis-templates
 
 # 用于提供给教务部
+.PHONY: undergrad
 undergrad: doc copy handbooks FORCE_MAKE
 	@if [ -z "$$version" ]; then \
 		echo -e "\e[32mPlease specify the version of the template you want to generate.\e[0m"; \
@@ -148,7 +162,7 @@ undergrad: doc copy handbooks FORCE_MAKE
 	cp -r $(SCAFFOLDDIR)/undergraduate-thesis-en/ ${UNDERGRAD_DEST_DIR}-${version}/undergraduate-thesis-en/
 	cp -r $(SCAFFOLDDIR)/paper-translation/ ${UNDERGRAD_DEST_DIR}-${version}/paper-translation/
 	cp ./bithesis.pdf ${UNDERGRAD_DEST_DIR}-${version}/'4-详细配置手册'.pdf
-	cp ./the-graduates-handbook/undergraduate-handbook.pdf ${UNDERGRAD_DEST_DIR}-${version}/'5-快速使用手册'.pdf
+	cp ./handbook/undergraduate-handbook.pdf ${UNDERGRAD_DEST_DIR}-${version}/'5-快速使用手册'.pdf
 	(cd ${UNDERGRAD_DEST_DIR}-${version}/undergraduate-thesis/ && zip -rm ../"1-BIThesis-本科毕设论文模板-${version}".zip . )
 	(cd ${UNDERGRAD_DEST_DIR}-${version}/undergraduate-thesis-en/ && zip -rm ../"2-BIThesis-本科毕设论文模板（全英文）-${version}".zip . )
 	(cd ${UNDERGRAD_DEST_DIR}-${version}/paper-translation/ && zip -rm ../"3-BIThesis-本科毕设外文翻译-${version}".zip . )
@@ -157,9 +171,9 @@ undergrad: doc copy handbooks FORCE_MAKE
 	rmdir ${UNDERGRAD_DEST_DIR}-${version}/paper-translation
 	zip -r ${UNDERGRAD_DEST_DIR}-${version}.zip ${UNDERGRAD_DEST_DIR}-${version}
 
+.PHONY: examples
 examples: cls
 	cp bithesis.cls $(EXAMPLEDIR)/cover/
 	cp bithesis.cls $(EXAMPLEDIR)/publications/
 	cd $(EXAMPLEDIR)/cover && latexmk && cd -
 	cd $(EXAMPLEDIR)/publications && latexmk && cd -
-

bithesis-doc.tex

@@ -600,7 +600,7 @@ \subsubsection{封面选项} \label{sec:cover}
 
   配置此选项以在部分模板封面中使用“华文细黑”，保证与 Word 模板中的字体一致。
 
-  在 Windows 和 MacOS 中，该字体已经安装；在 Linux 中一般需要用户自行安装（如果你是 WSL 用户，可参照\ref{sec:word-fonts}直接使用 Windows 下的字体）。
+  在 Windows 和 macOS 中，该字体已经安装；在 Linux 中一般需要用户自行安装（如果你是 WSL 用户，可参照\ref{sec:word-fonts}直接使用 Windows 下的字体）。
 \end{function}
 
 \begin{function}{cover/dilimiter}
@@ -1245,7 +1245,7 @@ \subsubsection{其他配置}
   \textit{此选项一般不需要用户自行修改。}
 
   本科生毕业设计模板（全英文专业）需要设置 Arial 字体。
-  在 Windows 和 MacOS 中，该字体已经安装；在 Linux 中需要用户自行安装（如果你是 WSL 用户，可参照\ref{sec:word-fonts}直接使用 Windows 下的字体）。
+  在 Windows 和 macOS 中，该字体已经安装；在 Linux 中需要用户自行安装（如果你是 WSL 用户，可参照\ref{sec:word-fonts}直接使用 Windows 下的字体）。
 \end{function}
 
 \begin{function}[added=2023-04-22, updated=2024-05-13]{misc/tabularFontSize}