本地使用说明

本页面介绍如何在本地使用模板。

本地编译需要在本地安装 TeX 系统，或者预编译的 Docker 镜像。

使用本地 TeX 系统编译模版

关于本地 TeX 系统的安装，可以参考「TeX 发行版及其安装 」，选择一个适合的发行版安装即可，这里不再赘述。

中文字体

SJTUThesis 由 CTeX 宏集提供中文支持，默认情况下可以自动检测操作系统选择字体配置。同时 CTeX 宏集也提供了相应选项以供在自动配置失效或用户有特殊需求的情况下使用。详情可以参考「CTeX 宏集手册」第 4.3 小节。

获取模板

下载压缩包

你可以在 Releases 页面中找到 SJTUThesis 的所有发布版本，推荐使用最新版本以避免一些问题。

从 1.0 版开始，模版使用 doc 和 DocStrip 工具进行代码的管理，不再支持直接克隆仓库代码使用的方式。对于普通用户，我们提供了开箱可用的发行包，本地使用请下载 sjtuthesis-vXXX.zip_{（XXX：版本号）}。如果你想使用最新的开发版，请参考后文「手动生成模版」一节。

SJTUThesis 现在也提供按 TDS（TeX Directory Structure）组织的发行包 sjtuthesis.tds.zip。你可以使用它将 SJTUThesis 模版类安装到你本地 TeX 系统中：

unzip sjtuthesis.tds.zip -d "$(kpsewhich --var-value TEXMFHOME)"/

手动生成模版

如果你想使用最新的开发版，你可以克隆仓库代码，手动生成模版。

git clone https://github.com/sjtug/SJTUThesis.git

模板的源代码代码位于 source/sjtuthesis.dtx 文件中，可以使用 make 工具生成模板：

make                # 生成模板并打包
make install        # 将 sjtuthesis 安装到本地的 TeX 系统中

生成的文件默认在 release 目录中。

编译模板

在 Linux 与 macOS 上编译

发行包中配套了 Makefile 文件。可以使用 GNU Make 工具调用 latexmk 程序，自动完成模板的多轮编译。Makefile 同时也提供了一些额外的实用功能。

make thesis.pdf     # 编译模板，生成 thesis.pdf
make clean          # 清理文件（不包括 thesis.pdf）
make cleanall       # 清理文件（包括 thesis.pdf）
make wordcount      # 字数统计

若需要生成用于提交盲审的论文（隐去作者、导师等信息），可在模版类选项中添加 review。

\documentclass[degree=master, zihao=-4, review]{sjtuthesis}

若需要在生成的论文中添加「原创性声明」和「版权使用授权书」的签名扫描件，可将 PDF 格式扫描件的路径作为参数传递给 \makeDeclareOriginality 和 \makeDeclareAuthorization 命令。

\makeDeclareOriginality[pdf/originality.pdf]
\makeDeclareAuthorization[pdf/authorization.pdf]

在 Windows 上编译

双击 compile.bat 即可完成编译过程，生成 thesis.pdf。

问题诊断

编译失败时，可以尝试手动逐次编译，定位故障。

xelatex -no-pdf thesis
biber --debug thesis
xelatex thesis
xelatex thesis

使用预编译的 Docker 镜像编译模版

也可以在本地使用预编译 Docker 镜像编译模版。与本地安装 TeX 系统相比，使用 Docker 的方式不会污染本地的环境，但要求用户对 Docker 有一定了解。

关于 Docker 的安装的问题不在本文的讨论范围。

这里介绍的是使用 MiKTeX 官方的 Docker 镜像 进行编译模版。网络上也可以找到很多基于 TeX Live 的第三方 Docker 镜像。与 TeX Live 不同，MiKTeX 可以在编译时自动安装需要的宏包，在 Docker 环境下，更符合轻量化的目标。

首先从 Docker hub 获取 Docker 镜像。

docker pull miktex/miktex

创建一个数据卷用存放自动安装的宏包，以供重复使用。

docker volume create --name miktex

首次使用前推荐先安装字体包 boondox，避免 latexmk 最后一步调用 xdvipdfmx 时可能产生的一些问题。

docker run --rm -ti         \
  -v miktex:/miktex/.miktex \
  -e MIKTEX_GID=$(id -g)    \
  -e MIKTEX_UID=$(id -u)    \
  miktex/miktex             \
  bash -c "mpm --install boondox; initexmf --update-fndb;"

使用如下命令编译模板。

docker run --rm -ti         \
  -v miktex:/miktex/.miktex \
  -v $(pwd):/miktex/work    \
  -e MIKTEX_GID=$(id -g)    \
  -e MIKTEX_UID=$(id -u)    \
  miktex/miktex             \
  latexmk -xelatex thesis.tex

此环境下 ctex 可能不能正确识别系统，会默认使用 Windows 字体配置。解决办法有很多：

一是在模版类选项中显式指定使用 Fandol 字体；

\documentclass[degree=bachelor, fontset=fandol]{sjtuthesis}

二是使用 Windows 字体编译，执行命令时将包含有 Windows 字体的目录作为数据卷挂载；

$ ls ~/.fonts
simfang.ttf  simhei.ttf  simkai.ttf  simli.ttf  simsunb.ttf  simsun.ttc  simyou.ttf
$ docker run --rm -ti               \
    -v miktex:/miktex/.miktex       \
    -v $HOME/.fonts:/miktex/.fonts  \
    -v $(pwd):/miktex/work          \
    -e MIKTEX_GID=$(id -g)          \
    -e MIKTEX_UID=$(id -u)          \
    miktex/miktex                   \
    latexmk -xelatex thesis.tex

你也可以参考「在线使用说明」中的方法配置自定义中文字体。