本地使用说明 - sjtug/SJTUThesis GitHub Wiki

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

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

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

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

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

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

make all                      # 编译生成 main.pdf
make clean                    # 删除编译所产生的中间文件
make cleanall                 # 删除 main.pdf 和所有中间文件
make wordcount                # 论文字数统计

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

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

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

./Compile.bat thesis
./Compile.bat clean
./Compile.bat cleanall
./Compile.bat wordcount

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

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

安装 “LaTeX Workshop” 插件后，选择 Recipe: latexmk (xelatex) 编译即可，并在设置中将 latex-workshop.latex.recipe.default 改为 lastUsed 以一直使用该选项编译。

如果遇到有全局配置导致的选项覆盖问题，直接在工作区的 .vscode/settings.json 添加下面的配置，以利用 .latexmkrc 文件进行编译。

{
    "latex-workshop.latex.recipes": [
        {
            "name": "latexmk-sjtuthesis",
            "tools": [
                "latexmk"
            ]
        }
    ],
    "latex-workshop.latex.tools": [
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-xelatex",
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-halt-on-error",
                "-time",
                "%DOC%"
            ]
        }
    ],
}

以及如果希望保存时即编译的话，考虑将 latex-workshop.latex.autoBuild.run 选项改为 onSave。在第一次对主文件按下编译按钮后即可在保存时自动开始编译。

在TexStudio的菜单栏中，Options-Configure TeXstudio界面中，修改以下两处：

Commands-Latexmk一项修改为latexmk.exe -silent -synctex=1 -xelatex %

Build-Default Compiler一项修改为txs:///latexmk

展开配置

注：至少在2023年初，原来的基于 MiKTeX 镜像的方法无法直接使用。临时替代方法包括：

1. 第一步不再拉取 Docker hub 上过时的镜像，而是使用源代码本地构建 Docker 镜像。例如：

   # （可选）删除宿主机上旧的 MiKTeX 镜像以释放空间
   git clone [email protected]:MiKTeX/docker-miktex.git
   cd docker-miktex
   docker build -t miktex/miktex:latest .

   后续其它步骤不变。

2. 使用基于 TeX Live 的镜像。例如 texlive/texlive

同时请参考该讨论。欢迎加入讨论/进一步完善该部分Wiki！

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

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

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

首先从 Docker hub 获取 Docker 镜像。

# 至少在2023年初已失效，请参考本节开始处的说明
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  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

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