article_tutor.typ

#import "article.typ": *
#import "@preview/showybox:2.0.1": showybox

#show: article.with(title: "Typst简明使用教程", authors: ("卓能文",))

#show raw.where(block: true, lang: "typst-ex"): it => {
  let txt = it.text
  showybox(
    [代码：
      #raw(txt, lang: "typc", block: true)],
    [结果：
      #eval(
        txt,
        mode: "markup",
        scope: (
          cstyle: cstyle,
          cwidth: cwidth,
          easytable: easytable,
          showybox: showybox,
          th: th,
          tr_alt: tr_alt,
        ),
      )],
  )
}

= Typst简介

Typst是撰写任何长篇文本（如论文、文章、科学论文、书籍、报告和家庭作业）的优秀工具。此外，Typst非常适合于编写任何包含数学符号的文档，例如在数学、物理和工程领域的论文。最后，由于其强大的风格化和自动化功能，它是任何一组具有共同风格的文件的绝佳选择，例如丛书。Typst文档风格和md文档类似，所以很容易上手，同时内置了强大的脚本功能及较多的排版原语，因此，能比较轻松完成优质文档的撰写及排版工作。

= Typst安装

Typst的本地安装非常简单，直接从#link("https://github.com/typst/typst/releases")下载适合自己操作系统的版本，解压到适当的地方即完成安装。另外，也可以在#link("https://typst.app")上注册账号，在线编辑typst文档，并下载生成的PDF文档。

对初学者编辑器建议采用`visual studio code`，并安装`Typst LSP`和`Typst Preview`插件。老手可以安装`sumlime text`并安装`typst`插件。

#warning[当你的文档内容比较多的时候，VS code反应将变得极其缓慢，建议对文件进行切分或换`sumlime text`编辑器。当然，最好用的编辑器还是helix！]

= Typst使用

== 创建文件

新建文本文档，以`.typ`为后缀。建议克隆#link("https://github.com/soarowl/typst.git")到本地，并将其中的`article.typ`复制到文档所在的目录，并适当进行修改。然后在文档头部添加如下内容：

```typc
#import "article.typ":*

#show: article.with(title: "Typst简明使用教程", authors: ("卓能文",))
```

== 章节设置

格式有点类似markdown，比较简单：

```typc
= 第一章
内容

== 第一节
内容

== 第二节
内容

== 第三节
内容

= 第二章
== 第一节
内容

== 第二节
内容

= 第三章
```

== 编译

```sh
typst compile filename.typ
```

如果没有任何错误，将输出`filename.pdf`文档。

== 注意几个特殊字符

#figure(
  caption: [特殊字符],
  kind: table,
  supplement: "表",
  easytable({
    let tr = tr_alt

    cwidth(15%, 1fr, 15%)
    cstyle(center, left, center)
    th[字符][意义][转义]
    tr[\*][两个\*字符之间的文字将加粗显示][\\\*]
    tr[\#][表示`typst`命令][\\\#]
    tr[\+][段首\+ 有序列表][\\\+]
    tr[\-][段首\- 无序列表][\\\-]
  }),
)

== 显示图片

建议将图片保存在一个特定的目录，如`images、img`之类的地方。

```typst-ex
#image("images/rose.jpg")
```

=== 设置宽度：

```typst-ex
#image("images/rose.jpg", width: 50%)
```

=== 居中显示：

```typst-ex
#align(center,image("images/rose.jpg", width: 50%))
```

=== 设置标题：

```typst-ex
#figure(
  caption: [玫瑰],
  supplement: "图",
  image("images/rose.jpg", width: 50%)
)
```

#info[放入`#figure`命令中的图片同时会在图形列表中出现。]

=== 多图并列

```typst-ex
#grid(
  columns: (1fr, 1fr),
  image("images/rose.jpg"),
  image("images/rose.jpg"),
)
```

=== 多图并列（带标题）

```typst-ex
#figure(
  caption: [多图并列（带标题）],
  supplement: "图",
  grid(
    columns: (1fr, 1fr),
    image("images/rose.jpg"),
    image("images/rose.jpg"),
  )
)
```

=== 多图并列含间距（带标题）

```typst-ex
#figure(
  caption: [多图并列含间距（带标题）],
  supplement: "图",
  grid(
    columns: (1fr, 1fr),
    gutter: 10pt,
    image("images/rose.jpg"),
    image("images/rose.jpg"),
  )
)
```

=== 多图并列（带子标题）

```typst-ex
#figure(
  caption: [多图并列（带子标题）],
  supplement: "图",
  grid(
    columns: (1fr, 1fr),
    gutter: 10pt,
    figure(
      caption: [玫瑰1],
      supplement: "图",
      image("images/rose.jpg")
    ),
    figure(
      caption: [玫瑰2],
      supplement: "图",
      image("images/rose.jpg")
    ),
  )
)
```

=== 多图并列（带子标题、子图无编号）

```typst-ex
#figure(
  caption: [多图并列（带子标题、子图无编号）],
  supplement: "图",
  grid(
    columns: (1fr, 1fr),
    gutter: 10pt,
    [#image("images/rose.jpg")玫瑰1],
    [#image("images/rose.jpg")玫瑰2],
  )
)
```

== 显示表格

````typst-ex
#figure(
  caption: [category表],
  kind: table,
  supplement: "表",
  easytable({
    let tr = tr_alt

    cwidth(1fr, 1fr, 1fr)
    cstyle(left, center, right)
    th[Header 1][Header 2][Header 3]
    tr[How][I][want]
    tr[a][drink,][alcoholic]
    tr[of][course,][after]
    tr[the][heavy][lectures]
    tr[involving][quantum][mechanics.]
  }),
)
````

#info[由于目前Typst中有bug，显示表格时，必须加上`kind`和`supplement`字段。]

更多用法请参考#link("https://github.com/maxcrees/tbl.typ")

== 显示公式

```typst-ex
勾股定理可用公式：$a^2 + b^2 = c^2$表示。
```

```typst-ex
#figure(
  caption: [数列求和],
  kind: math.equation,
  supplement: "公式",
  $ sum_(k=1)^n k = (n(n+1)) / 2 $
)
```

Typst默认只能显示一级公式，不能按章节重新计数，可采用第三方包`i-figured`实现，本模板已经内置。格式请参考`latex`相关文档。

== 显示代码

代码可以很容易添加，格式和markdown一样。

````typst-ex
```py3
def fibonaci(n):
    if n <= 1:
        return n
    else:
        return fibonaci(n - 1) + fibonaci(n - 2)
```
````

=== 添加标题

````typst-ex
#figure(
  caption: [计算斐波纳契],
  supplement: "代码",
```py3
def fibonaci(n):
    if n <= 1:
        return n
    else:
        return fibonaci(n - 1) + fibonaci(n - 2)
```
)
````

=== 显示代码文件

在Typst文档中添加太多代码，导致可读性降低，也不便于后续采用相应的工具进行编辑、更新、管理与维护，建议将代码组织在一个文件夹中。

````typst-ex
#figure(
  caption: [计算斐波纳契],
  supplement: "代码",
  raw(read("src/fibonaci.py"), lang: "py3", block: true)
)
````

== 标签与引用

在被引用的图表等地方用`<name>`设置标签，在打算引用的地方输入`@name`即可。name后面如果是中文，添加一个空格可避免编译错误。在`i-figured`中，需要在引用的地方添加`fig:、tbl:、lst:`等，形成`@fig:name`形式。如：@fig:rose 所示。

#figure(caption: [玫瑰], image("images/rose.jpg", width: 50%)) <rose>

== 参考文献设置

参考文献设置也比较简单，只需在文件尾部加入`#bibliography("example.yml", style: "gb-7714-2015-numeric")`即可。yml格式如下：

```yaml
audio-descriptions:
  affiliated:
    - names: Taylor, Dallas
      role: narrator
  author: Barrows, Miellyn Fitzwater
  date: 2017-02-07
  issue: 8
  parent:
    author: Taylor, Dallas
    title: Twenty Thousand Hertz
    type: Audio
  title: Audio Descriptions
  type: Audio
  url: https://www.20k.org/episodes/audio
barb:
  author: Günther-Haug, Barbara
  date: 2020
  language: de-DE
  location: München
  publisher: MVG
  title: Den Boden unter den Füßen verlieren
  type: Book
```

在文章适当的地方插入`@audio-descriptions`@audio-descriptions 或`@barb`@barb 这类的键。

= 写在最后

Typst相对来说还比较新，功能和latex相比稍弱，同时还存在一些bug。如果使用过程中有任何建议或模板上有什么问题，请到#link("https://github.com/soarowl/typst.git")提要求。

#counter(heading).update(0)
#set heading(numbering: "A.1")
= 附录

== article模板

#raw(read("article.typ"), lang: "typc", block: true)

== 本文档源码

#raw(read("article_tutor.typ"), lang: "typc", block: true)

#bibliography("basic.yml", style: "gb-7714-2015-numeric")