modern-sustech-thesis: v0.1.1-light

使用说明 Usage
- typst.app 网页版
- 离线编译
Quickstart of typst template
有关字体的补充说明
版本说明
特别鸣谢
写在后面

使用说明 Usage

模板已提交给 typst 网页端，仍需审核.

typst.app 中，搜索 modern-sustech-thesis 即可一键生成在线模板. 初次编译时间较长，此后编译速度与 markdown 体验无异.

typst.app 网页版

typst 网页端的模板库里已经上线，搜索 modern-sustech-thesis 即可一键生成在线模板. 初次编译时间较长，此后编译速度与 markdown 体验无异.

使用步骤：

打开 typst.app 从模板新建项目（start from template）
论文所需字体需要手动上传到你的项目文件列表.

点击左侧 Explore Files，上传字体文件，上传后的字体文件存储位置没有特殊要求，typst 拥有优秀的内核，可以完成自动搜索.

由于格式渲染引擎的核心需要指定字体的名称，我在模板测试阶段使用了若干标准字体，这些字体可以在我的 github 仓库 modern-sustech-thesis /template/fonts 里找到.

此外，可以手动更改字体配置，在正文前使用 '#set' 命令即可，由于标题、正文字体不同，此处大致语法如下：

// headings
  show heading.where(level: 1): it =>{
    set text(
      font: fonts.HeiTi,
      size: fonts.No3,
      weight: "regular",
    )
    align(center)[
      // #it
      #strong(it)
    ]
    text()[#v(0.5em)]
  }

  show heading.where(level: 2): it =>{
    set text(
      font: fonts.HeiTi,
      size: fonts.No4,
      weight: "regular"
      )
    it
    text()[#v(0.5em)]
  }

  show heading.where(level: 3): it =>{
    set text(
      font: fonts.HeiTi,
      size: fonts.No4-Small,
      weight: "regular"
      )
    it
    text()[#v(0.5em)] 
  }

  // paragraph
  set block(spacing: 1.5em)
  set par(
    justify: true,
    first-line-indent: 2em,
    leading: 1.5em)

headings 设定了各个登记标题的格式，其中一级标题需要居中对齐. 'font: fonts.HeiTi' 即为字体的关键参数，参数的值是字体的名称（字符串）. typst 将会在编译器内核、项目目录中搜索. typst 内核自带了 Source Sans（黑体）和 Source Serif（宋体）系列，但是中文论文所需的仿宋、楷体仍需自己上传.

离线编译

离线编译如果在命令行使用 'typst init "@preview/modern-sustech-thesis:0.1.0"'，则使用体验和网页端使用没有差别. 故本文考虑具有自定义格式需求的用户，作出额外说明.

项目结构：

格式渲染核心：lib.typ

格式的设置 '#set', '#show' 均是具有大括号内的生命周期，这种渲染是临时的，不会超出文件的作用. '#show' 会捕获满足格式的内容加以渲染，如无声明被捕获的对象，默认捕获 'doc'（全部文段）.

因此必须将渲染的核心打包成一个函数，在需要被渲染的内容前通过 '#show: xxx.with()[content]' 进行默认捕获. 其中方括号内是内容，在 typst 语法中如果只声明了函数调用 '#show: xxx.with()'，则函数后的部分都会被认为是文章的主体.

即： '#show: xxx.with(arg1, arg2, ..., body)' 中的最后一个参数可以通过如下方式传入：
- 'xxx.with(args, ..., [content])'
- 'xxx.with(args, ...)[content]'
渲染一个模板的工作分配给了两个部分：
- 静态内容编译. 如 cover, commitment 等只需要传递少量参数后可以渲染出完整界面的，我命名以静态内容.
  
  这些内容传递参数后渲染出的整个界面是静态的对象，因此可以直接调用函数（return 渲染后的界面）插入到调用函数的位置.
- 动态内容编译. 动态的设定很难超过当前的生命周期，除非使用 '#show' 不断传递. 在 content.typ 中，正文前使用 '#show: sustech-thesis.with()' 即将 content.typ 作为 body 参数交给 sustech-thesis() 这个函数渲染，因此，此时 body 作为被传递的参数进入了编译其中已经编译好了的 sustech-thesis，从而实现了格式控制.
  
  这样的格式控制分布在 configs 里的各个文件.
  
  此外，引用文献的设置采用了 typst 成员 Laurenz 教学模板里的设置，将 std-biliography 设置为某个 biliography 后才能夸文件引用，否则会出现标签引用相关错误.

// lib.typ
#let std-bibliography = bibliography
...

// content.typ
#show: sustech-thesis.with(
  ...,
  bibliography: bibliography(
    "refer.bib",
    title: [参考文献],
    style: "gb-7714-2015-numeric",
  ),
)

Quickstart of typst template

按照毕业设计要求，以 markdown 格式书写你的毕业论文，只需要：

在 configs/info 里填入个人信息. 如有标题编译错误（比如我默认了有三行标题），可以自行按照编译器提示把相关代码注释或者修改. 大体语法和内容与基本的编程语言无差别.
在 content.typ 里以 typst 特定的 markdown 语法书写你的论文内容. 有关 typst 中 markdown 的语法变更，个人认为的主要变化罗列如下：
- 标题栏使用 '=' 而非 '#'，'#' 在 typst 里是宏命令的开头.
- 数学公式不需要反斜杠，数学符号可以查阅：https://typst.app/docs/reference/symbols/sym/. 值得注意的是，typst 中语法不通过叠加的方式实现，如 “不等号” 在 LaTex 中是 '\not{=}'. 而在 typst 中，使用 'eq.not' 的方式来调用 'eq'（等号）的 'not'（不等）变体实现.
- 引用标签采用 '@label' 来实现，自定义标签通过 '' 来实现. 对于 BibTex 格式的引用（refer.bib），与 LaTex 思路相同，第一个缩略词将会被认定为 label.
自定义格式的思路. 如有额外的需要自定义格式的需求，可以自行学习 '#set', '#show' 命令，这可能需要一定的编程语言知识，后续我会更新部分简略教程在我的 github 仓库里：https://github.com/Duolei-Wang/lang-typst.
本模板的结构
1. 内容主体. 文章主体内容书写在 content.typ 文件中，附录部分书写在 appendix.typ 文件中.
2. 内容顺序. 文章内容顺序由 main.typ 决定，通过 typst 中 '#include' 指令实现了页面的插入.
3. 内容格式. 内容格式由 /sections/*.typ 控制，body.typ 控制了文章主体的格式，其余与名称一致. cover 为封面，commitment 为承诺书，outline 为目录，abstract 为摘要.

有关字体的补充说明

为了 typst/packages 审核方便，我将字体文件上传到了个人版本的仓库里：https://github.com/Duolei-Wang/fonts. 如有字体使用的需求，请将其下载后移动到当前目录下使用，typst 编译器会直接能找到目录下的可用字体.

经个人查阅，论文等要求的“宋体”等字体要求均是一个模糊的概念.

实际上，Windows 系统的宋体指中易宋体等，macOS 采用了华文宋体等. 为了避免不必要的纠纷，建议字体采用完全开源的字体，如：思源宋体、思源黑体、方正宋体、方正黑体、方正楷体、仿宋GB2312 等. 如担心字体审核问题，建议统一采用 GB2312 系列（缺点是部分生僻字缺失）. 本模板中使用的字体均为开源字体.

论文字体的选择在 font.typ 里进行了设置，可以修改 SongTi, HeiTi 等自变量的值来决定采用哪一个字体，这些自变量的值应当是字体的标准名称.

如果想查阅当前编译环境内的可选字体，可以通过以下两种方式：

#set text(
  font: ...
)

然后将光标悬停在 'font: ' 后，编译器会自动列出当前可用字体.

或者采用命令行指令 'typst fonts' 来查看可选字体.

版本说明

版本号：v0.1.0.

TODO:

引用格式 check.

特别鸣谢

南方科技大学本科毕业设计（论文）模板，论文格式参照南方科技大学本科生毕业设计（论文）撰写规范. 如有疏漏敬请谅解，本模板为本人毕业之前自用，如有使用，稳定性请自行负责.

本模板主要参考了 iydon 仓库的的 $\LaTeX$ 模板 sustechthesis；结构组织参照了 shuosc 仓库的 SHU-Bachelor-Thesis-Typst 模板；图片素材使用了 GuTaoZi 的同内容仓库里的模板.
感谢 SHU-Bachelor-Thesis 的结构组织让我学习到了很多，给我的页面组织提供了灵感，
在查找图片素材的时候，使用了 GuTaoZi 仓库 SUSTech-thesis-typst 里的svg 素材 LICENSE，特此感谢！

写在后面

笔者开发能力较弱，仅出于个人安利 typst 的需要开发了本模板. 如有开发、接管、功能需求请务必联系：

QQ: 782564506

mail: wangdl2020@mail.sustech.edu.cn

2catycm/modern-sustech-thesis