diff --git a/AdobeFangsongStd-Regular.otf b/AdobeFangsongStd-Regular.otf deleted file mode 100644 index fefe4b0..0000000 Binary files a/AdobeFangsongStd-Regular.otf and /dev/null differ diff --git a/AdobeHeitiStd-Regular.otf b/AdobeHeitiStd-Regular.otf deleted file mode 100644 index 7c4d336..0000000 Binary files a/AdobeHeitiStd-Regular.otf and /dev/null differ diff --git a/AdobeKaitiStd-Regular.otf b/AdobeKaitiStd-Regular.otf deleted file mode 100644 index 5f63bf7..0000000 Binary files a/AdobeKaitiStd-Regular.otf and /dev/null differ diff --git a/AdobeSongStd-Light.otf b/AdobeSongStd-Light.otf deleted file mode 100644 index 146197b..0000000 Binary files a/AdobeSongStd-Light.otf and /dev/null differ diff --git a/README-EN.md b/README-EN.md index 2973146..16d86e3 100644 --- a/README-EN.md +++ b/README-EN.md @@ -2,12 +2,10 @@ English | [中文](README.md) -> * **Note**: By using this template, you will obtain a **pdf** file as output. However, during the process of undergraduate thesis, there may be situations where you need to submit files in docx or other formats. In such cases, you can use some **pdf to docx conversion tools**, such as: [pdf2go.pdf-to-word](https://www.pdf2go.com/pdf-to-word)). -> * You do **not need to worry** about whether abandoning the docx template of the 1 system and choosing this LaTeX template will be affected by formatting issues. After all, those of us who use this template ([2017-ganler](https://github.com/ganler), [2018-skyleaworlder](https://github.com/skyleaworlder)) have not been required to reformat our papers due to formatting issues. - ## Sample Display -> The complete sample can be found in [Template Output Sample Display (Full Version)](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/discussions/21), in the pdf download link under "Assets" in the [Release page](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/releases) or [Overleaf Template PDF](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn.pdf). +> [!NOTE] +> A complete sample can be found in [Template Output Sample Display (Full Version)](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/discussions/21), in the pdf download link under "Assets" in the [Release page](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/releases) or [Overleaf Template PDF](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn.pdf). The following displays the "Cover", "Abstract in Chinese", "Table of Contents", "Main Content", "References" and "Acknowledgements" in order. @@ -22,211 +20,140 @@ The following displays the "Cover", "Abstract in Chinese", "Table of Contents", ## Usage -### 1. Directly use via **Overleaf** template +### Online Use -You can access our Overleaf template and use it directly through the following link: [![svg of overleaf-tongjithesis](https://img.shields.io/badge/Overleaf-TJ--CSCCG%2Ftongji--undergrad--thesis-green)](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn) +#### Using Directly via Overleaf Template -Please note that the Overleaf template is updated in a timely manner. We encourage you to use the template directly to write your undergraduate thesis and also to import the template into your own Overleaf project for use. Please refer to the next section of this document for specific instructions. +You can access and use our Overleaf template through the following link: [![svg of overleaf-tongjithesis](https://img.shields.io/badge/Overleaf-TJ--CSCCG%2Ftongji--undergrad--thesis-green)](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn) -> **Note!** When using the Overleaf template, be sure to check the compiler and main entry settings: -> -> * Set the `main.tex` file as the main entry file, not other `.tex` files in the project (especially `tongjithesis.cls` or `tongjithesis.sty`); -> * It is recommended to use `XeLaTeX` and `LuaLaTeX` compilers. This template does not support some compilers (such as `pdfLaTeX`). +> [!IMPORTANT] +> When using the Overleaf template, please check the compiler and main entry settings: +> +> - Set `main.tex` as the main entry file, instead of other `.tex` files in the project (especially `tongjithesis.cls` or `tongjithesis.sty`); +> - It is recommended to use the `XeLaTeX` or `LuaLaTeX` compilers, as some compilers (such as `pdfLaTeX`) are not supported by this template. -### 2. Import this repository on **Overleaf** +#### Importing This Repository on Overleaf -* Download this repository via "Code | Download ZIP" above the project file list on this repository's main page; -* Open [Overleaf](https://www.overleaf.com/); -* Upload the downloaded `zip` file to Overleaf by dragging and dropping it. +- Download this repository via `Code | Download ZIP` at the top of the repository home page file list; +- Open [Overleaf](https://www.overleaf.com/); +- Upload the downloaded `zip` file to Overleaf by dragging and dropping. -### 3. Using on Mac / Linux +#### Compiling in GitHub Actions -#### i. Install Python +The project is configured with GitHub Actions in `.github/workflows/*.yaml`. Pushing code to a fork repository or a template-generated repository will trigger tests. You can obtain build artifacts for multiple platforms from the `Summary | Artifacts` section of the workflow run associated with the commit. -- For Mac: Python comes pre-installed on most Macs. If you don't already have it, you can download and install it from the official website: https://www.python.org/downloads/mac-osx/ -- For Linux: Install Python by typing the following command in Terminal: -```shell -sudo apt-get install python3 -``` +(Enable GitHub Actions by checking `Settings | Actions | General | Allow all actions and reusable workflows`) -After installing Python, you need to set the environment variable ``PATH`` and add the path to Python to it. This will allow you to call the `minted` macro package correctly in LaTeX. +### Local Use -#### ii. Install `pygmentize` using `pip` +#### Installing $\TeX$ Distribution -Enter the following command in the terminal: -```shell -pip install Pygments -``` +We recommend installing TeX Live (Windows, Linux) or MacTeX (macOS) following the [official quick install guide](https://tug.org/texlive/quickinstall.html). -Note: If you encounter permissions problems during the installation process, you can run the above command from a command prompt with administrator privileges. +#### Supporting Code Highlighting -#### iii. Use tlmgr +This template supports code highlighting by incorporating the `minted` package. The `minted` package requires Python support, so you need to install Python and use `pip` to install `Pygments`. Afterwards, add the Python path with `Pygments` installed to the environment variable `PATH`, or configure as follows to ensure $\LaTeX$ can correctly invoke the `minted` package. -Download TeXLive and use `tlmgr` to download packages: +
Don't want to add this Python path to the environment variable `PATH`? -```shell -# The following commands aims at installing packages upon TeXLive without any packages. -# You can also install BasicTex: https://mirrors.chevalier.io/CTAN/systems/mac/mactex/mactex-basictex-20210325.pkg -sudo tlmgr update --self - -sudo tlmgr install adjustbox algorithmicx algorithms biber biblatex biblatex-gb7714-2015 bibtex booktabs \ - caption carlisle cases catchfile chinese-jfm chngcntr cleveref collectbox ctex dvips \ - enumitem environ extarrows fancybox fancyhdr fancyvrb float framed fvextra \ - gbt7714 gsftopk helvetic hologo ifplatform lastpage latexmk lineno \ - minted multirow mwe natbib needspace newtx nth oberdiek pdftexcmds realscripts rsfs setspace siunitx subfig \ - tcolorbox texcount texliveonfly threeparttable threeparttablex times titling tocloft \ - trimspaces txfonts ucs upquote was xcolor xecjk xstring zhnumber - -sudo tlmgr update --self --all -``` +You can add a redirect to the Python path of the `minted` package in the `main.tex` file: -#### iv. Build the project through Makefile +```latex +\renewcommand{\MintedPython}{/path/to/your/python} +``` -Thanks to the Makefile file of the [SJTUThesis](https://github.com/sjtug/SJTUThesis) project, you can build the project through Makefile: +
-```shell -make all # compile main.pdf -make ENGINE=$ENGINE all # use $ENGINE(where $ENGINE=-xelatex or -lualatex) to compile main.pdf -make clean # rm intermediate files -make cleanall # rm all intermediate files (including .pdf) -make wordcount # wordcount -``` +If you do not need code highlighting, please comment out the related content in the `minted` package. -### 4. Using on Windows +#### Building the Project -#### i. Install Python +Due to the complex file structure of this template, we do not recommend using commands like `latexmk` that come with TeX Live for compilation. -1. Download the Python installer: Download the Python installer from the [Python official website](https://www.python.org/downloads/windows/) (note: the downloaded version needs to match your operating system version and bit number). +We recommend building the project using the command line. Furthermore, we also support building the project in a complete UI environment using the LaTeX Workshop plugin in VS Code. -2. Run the Python installer: Double-click the downloaded installer and follow the prompts to install it. During installation, remember to check the `Add Python 3.x to PATH` option so that Python can be used from the command line. +##### Command Line -#### ii. Install `pygments` using `pip` +###### Makefile (Linux/macOS) -Enter the following command in the terminal: ```shell -pip install Pygments +make all # compile main.pdf +make ENGINE=$ENGINE all # use $ENGINE (where $ENGINE=-xelatex or -lualatex) to compile main.pdf +make clean # remove intermediate files +make cleanall # remove all intermediate files (including .pdf) +make wordcount # word count ``` -Note: If you encounter permissions problems during the installation process, you can run the above command from a command prompt with administrator privileges. - -Note: If you are concerned about the potential environmental contamination risks of adding a specific version of Python to your environment paths and wish to use a Python environment manager application, proceed as follows: -- Create a new Python environment and install the `pygments` module. -- Follow the comments in `main.tex` which specify the environment path directly in the file. - -#### iii. Install TeXLive - -Download `install-tl-windows.exe` from [here](https://www.tug.org/texlive/acquire-netinstall.html). - -Note: A data pack of about 8GB will be downloaded during the installation process, please be patient. - -#### iv. Build the project through Batchfile - -> Thanks to the Compile.bat file of the [SJTUThesis](https://github.com/sjtug/SJTUThesis) project. - -You can complete the corresponding operation with the following command: +###### Batchfile (Windows) ```bat -.\make.bat # the same to "make.bat thesis" -.\make.bat thesis # compile main.pdf -.\make.bat thesis $ENGINE # use $ENGINE(where $ENGINE=-xelatex or -lualatex) to compile main.pdf -.\make.bat clean # clean all work files by latexmk -c -.\make.bat cleanall # clean all work files and main.pdf by latexmk -C -.\make.bat wordcount # wordcount -.\make.bat help # read the manual -``` - -At this point, you are ready to write your paper with LaTex. If you prefer to operate in a full UI environment rather than the command line, please continue with the following. - -### 5. Using on VSCode - -#### i. Configure VSCode - -Install the LaTeX Workshop extension in the VSCode marketplace, then download this project and open it in the root directory. (LaTeX Workshop is just an extension, you still need to download the corresponding `TeXLive` for your platform) - -> **Note**: The following configurations are already included in the project's `.vscode/settings.json` file. Normally, when you start the LaTeX Workshop extension, it will automatically load the configuration. (The configuration in `.vscode/settings.json` will override the corresponding options in the global configuration file `settings.json`, so you do not need to modify the global configuration file.) - -```json -"latex-workshop.latex.recipe.default": "latexmk (xelatex)", -"latex-workshop.latex.tools": [ - { - "name": "xelatexmk", - "command": "latexmk", - "args": [ - "-xelatex", - "-synctex=1", - "-quiet", - "-interaction=nonstopmode", - "-file-line-error", - "-halt-on-error", - "-shell-escape", - "%DOC%" - ] - } -], -"latex-workshop.latex.recipes": [ - { - "name": "latexmk (xelatex)", - "tools": [ - "xelatexmk" - ] - } -] +.\make.bat # the same to "make.bat thesis" +.\make.bat thesis # compile main.pdf +.\make.bat thesis $ENGINE # use $ENGINE (where $ENGINE=-xelatex or -lualatex) to compile main.pdf +.\make.bat clean # clean all work files by latexmk -c +.\make.bat cleanall # clean all work files and main.pdf by latexmk -C +.\make.bat wordcount # wordcount +.\make.bat help # read the manual ``` -#### ii. Compile the project using Workshop features +##### Using VS Code and LaTeX Workshop Plugin -* Click the LaTeX button with the TEX icon on the left sidebar. -* Click `Recipe: latexmk (xelatex)` in the `Build LaTeX project` list to compile the `.pdf` file. +###### Configuring VS Code -### 6. Compile on GitHub Actions +Install the LaTeX Workshop plugin in VS Code, and then open the root directory of this project. -The project has been configured with GitHub Actions in `.github/workflows/*.yaml`, which can be triggered by pushing code to a forked repository or template-generated repository. Multi-platform build artifacts can be obtained through `Summary | Artifacts` in the corresponding workflow run of the commit. +###### Compile Project Using Workshop Features -(Open GitHub Actions by checking `Settings | Actions | General | Allow all actions and reusable workflows`) +Since we have configured the LaTeX Workshop plugin in `.vscode/settings.json`, you only need to: -### 7. Using Docker +- Select the `main.tex` file; +- Click the button with the $\TeX$ icon on the left sidebar; +- Click `Recipe: latexmk (xelatex)` from the `Build LaTeX project` list to compile the `.pdf` file. -See [tongji-undergrad-thesis-env](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-env) for detailed instructions. +Alternatively, the LaTeX Workshop plugin will automatically compile the file when you save it. -## Use double-sided printing version (optional) +##### Using in Docker -If you need to use the two-sided printing version, please change `\documentclass[oneside]{tongjithesis}` to `\documentclass[twoside]{tongjithesis}` in line 1 of `main.tex`. +For detailed usage, see [tongji-undergrad-thesis-env](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-env). -## Use more complete Adobe fonts (optional) +### Other Features -### Style modification +#### Double-Sided Printing -In order to use the more complete Adobe fonts from the font library, you need to make the following modifications: - -Find the following code snippet on line 10 of `style/tongjithesis.cls`: +If you need to use double-sided printing, simply change the first line in `main.tex` from ```latex -\LoadClass[UTF8,a4paper,fontset=fandol]{ctexart} +\documentclass[oneside]{tongjithesis} ``` -and modify it to: +to ```latex -\LoadClass[UTF8,a4paper,fontset=adobe]{ctexart} +\documentclass[twoside]{tongjithesis} ``` -With this modification, LaTeX will use the Adobe font set to render the document. +to enable it. -### Font installation +#### Rendering Rare Characters -The steps to install fonts are as follows: +Due to the default use of the Fandol font in this template, support for rare characters such as names and specific terms might not be adequate. We provide the Adobe font set in the [`fonts`](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/tree/fonts) branch of our GitHub repository. You can download and install these fonts, and then change the line in `style/tongjithesis.cls` from -1. In our repository root directory, we have attached four font files from Adobe (`AdobeFangsongStd-Regular.otf`, `AdobeKaitiStd-Regular.otf`, `AdobeHeitiStd-Regular.otf`, `AdobeSongStd-Light.otf`). If you use our template directly on Overleaf, you don't need to install it, but it should be noted that the compilation speed may be slightly slower. Therefore, we recommend that you compile locally. -2. If you use LaTeX on Windows, macOS or Linux, you need to install these four font files manually. Once installed, you are ready to compile. +```latex +\LoadClass[UTF8,a4paper,fontset=fandol]{ctexart} +``` -Note the support for the following compilation methods: +to -* If you are using Overleaf, only compiling with LuaLaTeX is supported. -* If you compile locally on Windows, macOS or Linux, you can choose to use XeLaTeX or LuaLaTeX. +```latex +\LoadClass[UTF8,a4paper,fontset=adobe]{ctexart} +``` -You can see the specific effect in Section 1.2.1 "Testing Rare Words" of the template document. +This modification will switch the rendering in the document to use the Adobe font set, enhancing support for rare characters. -With the steps above, you will be able to use Adobe font sets and render documents correctly. +> [!WARNING] +> Placing Adobe font files in the project's root directory and specifying the font path in `main.tex` is not always effective. Therefore, we recommend installing the Adobe fonts into the system font directory. +> +> Tests show that placing Adobe font files in the root directory of an Overleaf project and using LuaLaTeX for compilation works, but this method may slow down the compilation process. ## How to contribute to this project? @@ -256,30 +183,31 @@ This project uses the [LPPL-1.3c license](https://www.latex-project.org/lppl/lpp % https://github.com/TJ-CSCCG/tongji-undergrad-thesis ``` -## Notes on outstanding contributions +## Project History -* This project originated from [YukuanHU](https://github.com/YukuanHu)'s undergraduate thesis, which was uploaded on May 24, 2019. -* Since May 9, 2021, [ganler](https://github.com/ganler) has been maintaining a new project based on the above project, with enhanced functionality (project structure and platform adaptation). -* Starting on May 12, 2022, [skyleaworlder](https://github.com/skyleaworlder) started contributing to this project and integrated it into [TJ-CSCCG](http://github.com/TJ-CSCCG). They have continued to update and improve this project, and it has now become a well-established template for undergraduate theses. +- This project originated from [YukuanHU](https://github.com/YukuanHu)'s undergraduate thesis, which was uploaded on May 24, 2019. +- Starting May 9, 2021, [ganler](https://github.com/ganler) enhanced the functionalities (project structure and platform compatibility) based on the original project and began maintaining it. +- As of May 12, 2022, [skyleaworlder](https://github.com/skyleaworlder) started contributing to the project, integrated it into [TJ-CSCCG](http://github.com/TJ-CSCCG), and has continued to update and improve it. It has now become a comprehensive undergraduate thesis template. +- From April 2023, [RizhongLin](https://github.com/RizhongLin) began contributing to and managing the project. -We are very grateful for the contributions of these contributors, whose work has provided convenience and help to many students. +We deeply appreciate the efforts of these contributors, whose work has facilitated and assisted many students. -If you find this project helpful for your undergraduate thesis or dissertation, we hope you can acknowledge and express your gratitude in your acknowledgements. +If you find this template helpful for your thesis or dissertation, we hope you will acknowledge and honor these contributors in your acknowledgements section. ## Acknowledgements -We have learned a lot from the excellent open source projects of top universities: +We have learned a lot from excellent open-source projects from top universities: -* [sjtug/SJTUThesis](https://github.com/sjtug/SJTUThesis): makefile & batchfile -* [stone-zeng/fduthesis](https://github.com/stone-zeng/fduthesis): workflows +- [sjtug/SJTUThesis](https://github.com/sjtug/SJTUThesis): makefile & batchfile contributions. +- [stone-zeng/fduthesis](https://github.com/stone-zeng/fduthesis): workflows enhancements. -## Contact us +## Contact Information ```python # Python [ f'jiawei#@$.edu'.replace('#', '6').replace('$', 'illinois'), - 'jgli22@$.edu.cn'.replace('$', 'm.fudan'), - 'rizhonglin@!.edu.cn'.replace('!', 'tongji') + f'jgli22@$.edu.cn'.replace('$', 'm.fudan'), + f'rizhong.lin@$.%'.replace('$', 'epfl').replace('%', 'ch'), ] ``` diff --git a/README.md b/README.md index ad0c21e..0481908 100644 --- a/README.md +++ b/README.md @@ -2,236 +2,158 @@ 中文 | [English](README-EN.md) -> * **注意**：使用该模板你会获得 **pdf** 文件作为输出。但在毕业设计过程中可能存在需要提交 docx 等格式文件的场合，这时你可以使用一些 **pdf 转 docx 工具**，比如：[pdf2go.pdf-to-word](https://www.pdf2go.com/pdf-to-word))。 -> * 你 **不需要担心** “抛弃 1 系统的 docx 模板而选用本 LaTeX 模板是否会受到影响”，毕竟使用该模板的我们（[2017-ganler](https://github.com/ganler), [2018-skyleaworlder](https://github.com/skyleaworlder)）都没有因格式问题而被勒令重新排版论文。 - ## 样例展示 +> [!NOTE] > 完整样例可见 [模板输出样例展示（完整版）](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/discussions/21)、[Release 页](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/releases) 中 "Assets" 下的 pdf 下载链接或 [Overleaf 模版 PDF](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn.pdf)。 以下依次展示 “封面”、“中文摘要”、“目录”、“主要内容”、“参考文献” 与 “谢辞”。

- - - - - - + + + + + +

## 使用方法 -### 1. 通过 **Overleaf** 模板直接使用 +### 在线使用 -您可以通过以下链接访问我们的 Overleaf 模板并使用：[![svg of overleaf-tongjithesis](https://img.shields.io/badge/Overleaf-TJ--CSCCG%2Ftongji--undergrad--thesis-green)](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn) +#### 通过 Overleaf 模板直接使用 -请注意，该 Overleaf 模板已经及时更新。我们鼓励您直接使用该模板来编写您的本科毕业论文，也可以将该模板导入到自己的 Overleaf 项目中进行使用。具体操作方法请参考本文档下一节。 +您可以通过以下链接访问我们的 Overleaf 模板并使用：[![svg of overleaf-tongjithesis](https://img.shields.io/badge/Overleaf-TJ--CSCCG%2Ftongji--undergrad--thesis-green)](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn) -> **注意！** 在使用 Overleaf 模板时，请务必检查编译器和主入口的设置： -> -> * 将 `main.tex` 文件设为主入口文件，而不是项目中的其他 `.tex` 文件（尤其是 `tongjithesis.cls` 或 `tongjithesis.sty`）； -> * 推荐使用 `XeLaTeX` 和 `LuaLaTeX` 编译器，本模板不支持某些编译器（如 `pdfLaTeX`）。 +> [!IMPORTANT] +> 在使用 Overleaf 模板时，请检查编译器和主入口的设置： +> +> - 将 `main.tex` 文件设为主入口文件，而不是项目中的其他 `.tex` 文件（尤其是 `tongjithesis.cls` 或 `tongjithesis.sty`）； +> - 推荐使用 `XeLaTeX` 和 `LuaLaTeX` 编译器，本模板不支持某些编译器（如 `pdfLaTeX`）。 +#### 在 Overleaf 上导入本仓库 -### 2. 在 **Overleaf** 上导入本仓库 +- 通过本仓库主页项目文件列表上方的 `Code | Download ZIP` 下载本仓库； +- 打开 [Overleaf](https://www.overleaf.com/)； +- 通过拖拽下载的 `zip` 文件上传至 Overleaf。 -* 通过本仓库主页项目文件列表上方的 “Code | Download ZIP” 下载本仓库； -* 打开 [Overleaf](https://www.overleaf.com/)； -* 通过拖拽下载的 `zip` 文件上传至 Overleaf。 +#### 在 GitHub Actions 中编译 -### 3. 在 Mac / Linux 上使用 +项目以 `.github/workflows/*.yaml` 配置了 GitHub Actions，push 代码到 fork 仓库或 template-generated 仓库均可触发测试。可通过 commit 对应的 workflow run 中的 `Summary | Artifacts` 获得多平台构建产物。 -#### i. 安装 Python +（通过勾选 `Settings | Actions | General | Allow all actions and reusable workflows` 打开 GitHub Actions） -- 对于 Mac：大多数 Mac 上已经预装了 Python。如果你还没有安装，可以从官网下载安装：https://www.python.org/downloads/mac-osx/ -- 对于 Linux：在终端中输入以下命令来安装 Python： -```shell -sudo apt-get install python3 -``` +### 本地使用 -当安装完 Python 后，你需要设置环境变量 `PATH`，将 Python 的路径添加进去。这样才能在 LaTeX 中正确调用 `minted` 宏包。 +#### 安装 $\TeX$ 发行版 -#### ii. 使用 `pip` 安装 `pygmentize` +我们建议参照[官方快速安装指南](https://tug.org/texlive/quickinstall.html)安装 TeX Live（Windows、Linux）或 MacTeX（macOS）。 -在终端中输入以下命令： -```shell -pip install Pygments -``` +#### 支持代码高亮 -注意：如果你在安装过程中遇到了权限问题，可以在命令提示符中使用管理员权限运行以上命令。 +本模板通过引入 `minted` 宏包支持代码高亮。`minted` 宏包需要 Python 环境支持，因此您需要安装 Python 并使用 `pip` 安装 `Pygments`。此后，需要将装有 `Pygments` 的 Python 路径添加到环境变量 `PATH` 中，或者按照下面的说明配置，使得 $\LaTeX$ 能够正确调用 `minted` 宏包。 -#### iii. 使用 tlmgr +
不想将此 Python 路径添加到环境变量 `PATH` 中？ -下载 TeXLive，并使用 `tlmgr` 下载宏包： +可以在 `main.tex` 文件中添加重定向 `minted` 宏包的 Python 路径： -```shell -# The following commands aims at installing packages upon TeXLive without any packages. -# You can also install BasicTex: https://mirrors.chevalier.io/CTAN/systems/mac/mactex/mactex-basictex-20210325.pkg -sudo tlmgr update --self - -sudo tlmgr install adjustbox algorithmicx algorithms biber biblatex biblatex-gb7714-2015 bibtex booktabs \ - caption carlisle cases catchfile chinese-jfm chngcntr cleveref collectbox ctex dvips \ - enumitem environ extarrows fancybox fancyhdr fancyvrb float framed fvextra \ - gbt7714 gsftopk helvetic hologo ifplatform lastpage latexmk lineno \ - minted multirow mwe natbib needspace newtx nth oberdiek pdftexcmds realscripts rsfs setspace siunitx subfig \ - tcolorbox texcount texliveonfly threeparttable threeparttablex times titling tocloft \ - trimspaces txfonts ucs upquote was xcolor xecjk xstring zhnumber - -sudo tlmgr update --self --all +```latex +\renewcommand{\MintedPython}{/path/to/your/python} ``` -#### iv. 通过 Makefile 构建项目 - -> 感谢 [SJTUThesis](https://github.com/sjtug/SJTUThesis) 项目的 Makefile 文件。 - -你可以通过下列指令完成对应操作： - -```shell -make all # compile main.pdf -make ENGINE=$ENGINE all # use $ENGINE(where $ENGINE=-xelatex or -lualatex) to compile main.pdf -make clean # rm intermediate files -make cleanall # rm all intermediate files (including .pdf) -make wordcount # wordcount -``` +
-### 4. 在 Windows 上使用 +若您不需要代码高亮，请将 `minted` 宏包相关内容注释掉。 +#### 构建项目 -#### i. 安装 Python +因为本模版的文件结构较为复杂，我们不推荐直接使用 TeX Live 自带的 `latexmk` 等命令进行编译。 -1. 下载 Python 安装程序：在 [Python 官网](https://www.python.org/downloads/windows/) 上下载 Python 的安装程序（注意：下载的版本需要与你的操作系统版本和位数相匹配）。 +我们推荐使用命令行构建项目。进一步地，我们也支持通过 VS Code 的 LaTeX Workshop 插件，在一个完整的 UI 环境中构建项目。 -2. 运行 Python 安装程序：双击下载的安装程序并按照提示进行安装。在安装过程中，记得勾选 `Add Python 3.x to PATH` 选项，这样 Python 才能在命令行中使用。 +##### 通过命令行 -#### ii. 使用 `pip` 安装 `pygments` +###### Makefile (Linux/macOS) -在终端中输入以下命令： ```shell -pip install Pygments +make all # compile main.pdf +make ENGINE=$ENGINE all # use $ENGINE(where $ENGINE=-xelatex or -lualatex) to compile main.pdf +make clean # rm intermediate files +make cleanall # rm all intermediate files (including .pdf) +make wordcount # wordcount ``` -注意：如果你在安装过程中遇到了权限问题，可以在命令提示符中使用管理员权限运行以上命令。 - -注意：若您担忧将某个具体版本的 Python 加入环境变量存在潜在的环境污染隐患，希望使用 Python 环境管理应用，则步骤如下： -- 创建一个新的 Python 环境，在环境中安装 `pygments` 模块 -- 按照`main.tex`中的注释，在文件中直接指定该环境路径。 - -#### iii. 安装 TeXLive - -通过 [此处](https://www.tug.org/texlive/acquire-netinstall.html) 下载 `install-tl-windows.exe`。 - -注意：安装过程中会下载8GB左右的数据，请耐心等待。 - -#### iv. 通过 Batchfile 构建项目 - -> 感谢 [SJTUThesis](https://github.com/sjtug/SJTUThesis) 项目的 Compile.bat 文件。 - -你可以通过下列指令完成对应操作： +###### Batchfile (Windows) ```bat -.\make.bat # the same to "make.bat thesis" -.\make.bat thesis # compile main.pdf -.\make.bat thesis $ENGINE # use $ENGINE(where $ENGINE=-xelatex or -lualatex) to compile main.pdf -.\make.bat clean # clean all work files by latexmk -c -.\make.bat cleanall # clean all work files and main.pdf by latexmk -C -.\make.bat wordcount # wordcount -.\make.bat help # read the manual -``` - -至此，您已经可以借助LaTex撰写论文了。若相比命令行，您更倾向于在一个完整的UI环境中进行操作，请继续查阅以下内容。 - -### 5. 在 VSCode 上使用 - -#### i. 配置 VSCode - -在插件市场中安装 LaTeX Workshop 插件，此后下载该项目，并在该项目根目录打开。（LaTeX Workshop 只是一个插件，仍需要下载对应平台下的 `TeXLive`） - -> **注意**：下列配置已被项目中 `.vscode/settings.json` 包含。正常情况下，启动 LaTeX Workshop 插件时会自动装载配置。（`.vscode/settings.json` 中的配置会覆盖全局配置文件 `settings.json` 中对应选项，因此不必修改全局配置文件） - -```json -"latex-workshop.latex.recipe.default": "latexmk (xelatex)", -"latex-workshop.latex.tools": [ - { - "name": "xelatexmk", - "command": "latexmk", - "args": [ - "-xelatex", - "-synctex=1", - "-quiet", - "-interaction=nonstopmode", - "-file-line-error", - "-halt-on-error", - "-shell-escape", - "%DOC%" - ] - } -], -"latex-workshop.latex.recipes": [ - { - "name": "latexmk (xelatex)", - "tools": [ - "xelatexmk" - ] - } -] +.\make.bat # the same to "make.bat thesis" +.\make.bat thesis # compile main.pdf +.\make.bat thesis $ENGINE # use $ENGINE (where $ENGINE=-xelatex or -lualatex) to compile main.pdf +.\make.bat clean # clean all work files by latexmk -c +.\make.bat cleanall # clean all work files and main.pdf by latexmk -C +.\make.bat wordcount # wordcount +.\make.bat help # read the manual ``` -#### ii. 通过 Workshop 提供的功能编译项目 +##### 通过 VS Code 及 LaTeX Workshop 插件 -* 点击左侧边栏中带有 TEX 图标的 LaTeX 按钮； -* 点击 `Build LaTeX project` 列表中的 `Recipe: latexmk (xelatex)` 编译 `.pdf` 文件。 +###### 配置 VS Code -### 6. 在 GitHub Actions 中编译 +在 VS Code 中安装 LaTeX Workshop 插件，然后打开本项目根目录。 -项目以 `.github/workflows/*.yaml` 配置了 GitHub Actions，push 代码到 fork 仓库或 template-generated 仓库均可触发测试。可通过 commit 对应的 workflow run 中的 `Summary | Artifacts` 获得多平台构建产物。 +###### 通过 Workshop 提供的功能编译项目 -（通过勾选 `Settings | Actions | General | Allow all actions and reusable workflows` 打开 GitHub Actions） +因为我们已经在 `.vscode/settings.json` 中配置了 LaTeX Workshop 插件，所以您只需要： -### 7. 在 Docker 中使用 - -详细使用方法见 [tongji-undergrad-thesis-env](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-env)。 +- 选中 `main.tex` 文件； +- 点击左侧边栏中带有 $\TeX$ 图标的按钮； +- 点击 `Build LaTeX project` 列表中的 `Recipe: latexmk (xelatex)` 编译 `.pdf` 文件。 -## 使用双面打印版（可选） +或者，LaTeX Workshop 插件会在您保存文件时自动编译。 -如果您需要使用双面打印版，请在 `main.tex` 中将第 1 行的 `\documentclass[oneside]{tongjithesis}` 修改为 `\documentclass[twoside]{tongjithesis}`。 +##### 在 Docker 中使用 -## 使用字库更完整的 Adobe 字体（可选） +详细使用方法见 [tongji-undergrad-thesis-env](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-env)。 -### 样式修改 +### 其他功能 -为了使用字库更完全的 Adobe 字体，您需要进行以下修改： +#### 双面打印版 -在 `style/tongjithesis.cls` 的第 10 行找到如下代码段： +如果您需要使用双面打印版，请在 `main.tex` 中将第 1 行的 ```latex -\LoadClass[UTF8,a4paper,fontset=fandol]{ctexart} +\documentclass[oneside]{tongjithesis} ``` -并将其修改为： +修改为 ```latex -\LoadClass[UTF8,a4paper,fontset=adobe]{ctexart} +\documentclass[twoside]{tongjithesis} ``` -这样修改后，LaTeX 将使用 Adobe 字体集来渲染文档。 +即可。 -### 字体安装 +#### 渲染生僻字 -字体安装的步骤如下： +由于本模版默认使用 Fandol 字体，对于姓名、专有名词等生僻字的支持可能不够完善。我们在本模版 GitHub 仓库的 [`fonts`](https://github.com/TJ-CSCCG/tongji-undergrad-thesis/tree/fonts) 分支中提供了 Adobe 字体集，您可以下载、安装这些字体，然后在 `style/tongjithesis.cls` 中将 -1. 在我们的仓库根目录中，我们已经附上了 Adobe 的四个字体文件。如果您在 Overleaf 上直接使用我们的模板，您无需进行安装，但需要注意的是编译速度可能会稍慢。因此，我们建议您在本地进行编译。 -2. 如果您在 Windows、macOS 或 Linux 上使用 LaTeX，您需要手动安装这四个字体文件。安装完成后，您就可以进行编译了。 - -请注意以下编译方式的支持情况： +```latex +\LoadClass[UTF8,a4paper,fontset=fandol]{ctexart} +``` -* 如果您在 Overleaf 上使用，只支持使用 LuaLaTeX 进行编译。 -* 如果您在 Windows、macOS 或 Linux 上进行本地编译，您可以选择使用 XeLaTeX 或 LuaLaTeX。 +修改为 -您可以在模板文档的 1.2.1 小节 “测试生僻字” 中查看具体效果。 +```latex +\LoadClass[UTF8,a4paper,fontset=adobe]{ctexart} +``` -通过以上步骤，您将能够使用 Adobe 字体集并正确渲染文档。 +这样修改后，LaTeX 将使用 Adobe 字体集来渲染文档。您可以在模板文档的 1.2.1 小节 “测试生僻字” 中查看具体效果。 +> [!WARNING] +> 将 Adobe 字体文件放置在项目根目录下并在 `main.tex` 中指定字体路径的方式并不总是有效。因此，我们建议您将 Adobe 字体文件安装到系统字体目录中。 +> +> 经测试，在 Overleaf 项目的根目录下放置 Adobe 字体文件，并只在使用 LuaLaTeX 编译的方式是有效的，但这种方式可能会导致编译速度变慢。 ## 如何为该项目贡献代码？ @@ -261,11 +183,12 @@ pip install Pygments % https://github.com/TJ-CSCCG/tongji-undergrad-thesis ``` -## 有关突出贡献的说明 +## 项目历史 -* 该项目起源于 [YukuanHU](https://github.com/YukuanHu) 的本科毕业设计论文，论文于 2019.05.24 上传； -* 2021.05.09 起，[ganler](https://github.com/ganler) 以上述项目为基础，增强其功能（项目结构与平台适配）并开始维护新项目。 -* 2022.05.12 起，[skyleaworlder](https://github.com/skyleaworlder) 开始贡献本项目，并将其整合进 [TJ-CSCCG](http://github.com/TJ-CSCCG)，并持续对该项目进行更新和改进，目前已经成为一个完善的本科毕业论文模板。 +- 该项目起源于 [YukuanHU](https://github.com/YukuanHu) 的本科毕业设计论文，论文于 2019.05.24 上传； +- 2021.05.09 起，[ganler](https://github.com/ganler) 以上述项目为基础，增强其功能（项目结构与平台适配）并开始维护新项目。 +- 2022.05.12 起，[skyleaworlder](https://github.com/skyleaworlder) 开始贡献本项目，并将其整合进 [TJ-CSCCG](http://github.com/TJ-CSCCG)，并持续对该项目进行更新和改进，目前已经成为一个完善的本科毕业论文模板。 +- 2023.04 起，[RizhongLin](https://github.com/RizhongLin) 开始贡献本项目，并负责项目的维护和更新。 我们非常感谢以上贡献者的付出，他们的工作为更多同学提供了方便和帮助。 @@ -275,8 +198,8 @@ pip install Pygments 我们从顶尖高校的优秀开源项目中学到了很多： -* [sjtug/SJTUThesis](https://github.com/sjtug/SJTUThesis): makefile & batchfile -* [stone-zeng/fduthesis](https://github.com/stone-zeng/fduthesis): workflows +- [sjtug/SJTUThesis](https://github.com/sjtug/SJTUThesis): makefile & batchfile +- [stone-zeng/fduthesis](https://github.com/stone-zeng/fduthesis): workflows ## 联系方式 @@ -284,7 +207,7 @@ pip install Pygments # Python [ f'jiawei#@$.edu'.replace('#', '6').replace('$', 'illinois'), - 'jgli22@$.edu.cn'.replace('$', 'm.fudan'), - 'rizhonglin@!.edu.cn'.replace('!', 'tongji') + f'jgli22@$.edu.cn'.replace('$', 'm.fudan'), + f'rizhong.lin@$.%'.replace('$', 'epfl').replace('%', 'ch'), ] ``` diff --git a/main.tex b/main.tex index 4a737d3..90d9f97 100644 --- a/main.tex +++ b/main.tex @@ -4,14 +4,14 @@ \begin{document} \input{sections/frontcover.tex} -\clearchapterpage +\cleardoublepage \pagestyle{firststyle} \input{sections/00_abstract.tex} \clearpage \tableofcontents %放置目录 -\clearchapterpage +\cleardoublepage \pagestyle{mainstyle} \input{sections/01_intro} diff --git a/style/tongjithesis.cls b/style/tongjithesis.cls index 69ec3fc..91ebf28 100644 --- a/style/tongjithesis.cls +++ b/style/tongjithesis.cls @@ -9,15 +9,6 @@ % 该类提供包括但不限于 \heiti \zihao 等指令 \LoadClass[UTF8,a4paper,fontset=fandol]{ctexart} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% \LoadClass[UTF8,a4paper,fontset=adobe]{ctexart} -% 若需要使用包含所有 GBK 字符的 Adobe 字体，可使用如上命令 -% 需要完成 README.md 中提到的字体安装步骤 -% Overleaf 上使用该命令时编译速度会变慢很多，建议本地编译 -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % 若你想要用句点（．）替换句号（。） % 可以打开下面的注释 @@ -27,17 +18,6 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% 在 Windows 上使用时： -% 若你想避免将 Python 加入环境变量，可以在此手动指定 Python 环境 -% 打开下面的注释，并替换尖括号 <> 中的路径 -% e.g. {/python.exe} -> {C:/software/Anaconda3/envs/latex/python.exe} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% \newcommand{\myPython}{/python.exe} -% \renewcommand{\MintedPygmentize}{\myPython\space -m pygments} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - % 设置页边距 \setlength{\headheight}{43pt} \RequirePackage[a4paper,top=4.2cm,bottom=2.7cm,left=3.3cm,right=1.8cm]{geometry} @@ -408,14 +388,4 @@ \textbf{Key words:\quad}#2 } \par -} - -\makeatletter -\def\clearchapterpage{% - \@ifclasswith{tongjithesis}{twoside}{% - \cleardoublepage % 如果使用双面模式的 tongjithesis 文档类，使用 \cleardoublepage 清除页面 - }{% - \clearpage % 否则，使用 \clearpage 清除页面 - } -} -\makeatother \ No newline at end of file +} \ No newline at end of file