docs: complete English documentation

touying-typ · Mar 7, 2024 · 2b36dee · 2b36dee
1 parent e7aa185
commit 2b36dee
Show file tree

Hide file tree

Showing 18 changed files with 288 additions and 288 deletions.
diff --git a/README.md b/README.md
@@ -92,6 +92,8 @@ Hello, Typst!
 
 It's simple. Congratulations on creating your first Touying slide! 🎉
 
+**Tip:** You can use Typst syntax like `#import "config.typ": *` or `#include "content.typ"` to implement Touying's multi-file architecture.
+
 **Warning:** The comma in `#let (slide,) = utils.slides(s)` is necessary for the unpacking syntax.
 
 

diff --git a/docs/docs/build-your-own-theme.md b/docs/docs/build-your-own-theme.md
diff --git a/docs/docs/code-styles.md b/docs/docs/code-styles.md
@@ -2,11 +2,11 @@
 sidebar_position: 4
 ---
 
-# 代码风格
+# Code Style
 
-## 简单风格
+## Simple Style
 
-如果我们只是需要简单使用，我们可以直接在标题下输入内容，就像是在编写正常 Typst 文档一样。这里的标题有着分割页面的作用，同时我们也能正常地使用 `#pause` 等命令实现动画效果。
+If we only need simplicity, we can directly input content under the title, just like writing a normal Typst document. The title here serves to divide the pages, and we can use commands like `#pause` to achieve animation effects.
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -31,16 +31,15 @@ Hello, Typst!
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/f5bdbf8f-7bf9-45fd-9923-0fa5d66450b2)
 
-并且你可以使用空标题 `==` 创建一个新页，这个技巧也有助于清除上一个标题的继续应用。
+You can use an empty title `==` to create a new page. This technique also helps clear the continuation of the previous title.
 
-PS：我们可以使用 `#slides-end` 记号来标志 `#show: slides` 的结束。
+PS: We can use the `#slides-end` marker to signify the end of `#show: slides`.
 
+## Block Style
 
-## 块风格
+Many times, using simple style alone cannot achieve all the functions we need. For more powerful features and clearer structure, we can also use block style in the form of `#slide[...]`. The `#slide` function needs to be unpacked using the syntax `#let (slide,) = utils.slides(s)` to be used correctly after `#show: slides`.
 
-很多时候，仅仅使用简单风格并不能实现我们需要的所有功能，为了更强大的功能和更清晰的结构，我们同样可以使用 `#slide[...]` 形式的块风格，其中 `#slide` 函数需要使用 `#let (slide,) = utils.slides(s)` 语法进行解包，才能正常在 `#show: slides` 后使用。
-
-例如上面的例子就可以改造成
+For example, the previous example can be transformed into:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -65,19 +64,18 @@ PS：我们可以使用 `#slides-end` 记号来标志 `#show: slides` 的结束
 ]
 ```
 
-这样做的好处有很多：
-
-1. 很多时候，我们不只是需要默认的 `#slide[...]`，还需要 `#focus-slide[...]` 这些特殊的 `slide` 函数；
-2. 不同主题的 `#slide[...]` 函数可能有比默认更多的参数，例如 university 主题的 `#slide[...]` 函数就会有着 `subtitle` 参数；
-3. 只有 `slide` 函数才可以通过回调风格的内容块来使用 `#only` 和 `#uncover` 函数实现复杂的动画效果。
-4. 能有着更清晰的结构，通过辨别 `#slide[...]` 块，我们可以很容易地分辨出 slides 的具体分页效果。
+There are many advantages to doing this:
 
+1. Many times, we not only need the default `#slide[...]` but also special `slide` functions like `#focus-slide[...]`.
+2. Different themes' `#slide[...]` functions may have more parameters than the default, such as the university theme's `#slide[...]` function having a `subtitle` parameter.
+3. Only `slide` functions can use the callback-style content block to achieve complex animation effects with `#only` and `#uncover` functions.
+4. It has a clearer structure. By identifying `#slide[...]` blocks, we can easily distinguish the specific pagination effects of slides.
 
-## 约定优于配置
+## Convention Over Configuration
 
-你可能注意到了，在使用 simple 主题时，我们使用一级标题会自动创建一个 section slide，这是因为 simple 主题注册了一个 `s.methods.touying-new-section-slide` 方法，因此 touying 会默认调用这个方法。
+You may have noticed that when using the simple theme, using a level-one title automatically creates a section slide. This is because the simple theme registers an `s.methods.touying-new-section-slide` method, so Touying will automatically call this method.
 
-如果我们不希望它自动创建这样一个 section slide，我们可以将这个方法删除：
+If we don't want it to automatically create such a section slide, we can delete this method:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -103,9 +101,9 @@ Hello, Typst!
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/17a89a59-9491-4e1f-95c0-09a22105ab35)
 
-如你所见，这样就只会剩下两页，而默认的 section slide 就会消失了。
+As you can see, there are only two pages left, and the default section slide is gone.
 
-同理，我们也可以注册一个新的 section slide：
+Similarly, we can register a new section slide:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -138,15 +136,15 @@ Hello, Typst!
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/5305efda-0cd4-42eb-9f2e-89abc30b6ca2)
 
-同样地，我们也可以修改 `s.methods.touying-new-subsection-slide` 来对 `subsection` 做同样的事。
+Similarly, we can modify `s.methods.touying-new-subsection-slide` to do the same for `subsection`.
 
-实际上，除了 `s.methods.touying-new-section-slide`，另一个特殊的 `slide` 函数就是 `s.methods.slide` 函数，它会在简单风格里没有显示使用 `#slide[...]` 的情况下默认被调用。
+In fact, besides `s.methods.touying-new-section-slide`, another special `slide` function is the `s.methods.slide` function, which will be called by default in simple style when `#slide[...]` is not explicitly used.
 
-同时，由于 `#slide[...]` 被注册在了 `s.slides = ("slide",)` 里，因此 `section`，`subsection` 和 `title` 参数会被自动传入，而其他的如 `#focus-slide[...]` 则不会自动传入这三个参数。
+Also, since `#slide[...]` is registered in `s.slides = ("slide",)`, the `section`, `subsection`, and `title` parameters will be automatically passed, while others like `#focus-slide[...]` will not automatically receive these three parameters.
 
-:::tip[原理]
+:::tip[Principle]
 
-实际上，你也可以不使用 `#show: slides` 和 `utils.slides(s)`，而是只使用 `utils.methods(s)`，例如
+In fact, you can also not use `#show: slides` and `utils.slides(s)`, but only use `utils.methods(s)`, for example:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -164,6 +162,6 @@ Hello, Typst!
 ]
 ```
 
-这时候需要手动传入 `section`、`subsection` 和 `title`，但是会有更好的性能，适合需要更快的性能的情况，例如超过数十数百页的情形。
+Here, you need to manually pass in `section`, `subsection`, and `title`, but it will have better performance, suitable for cases where faster performance is needed, such as when there are more than dozens or hundreds of pages.
 
 :::
diff --git a/docs/docs/dynamic/other.md b/docs/docs/dynamic/other.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 # Other Animations

diff --git a/docs/docs/global-settings.md b/docs/docs/global-settings.md
@@ -2,13 +2,13 @@
 sidebar_position: 6
 ---
 
-# 全局设置
+# Global Settings
 
-## 全局样式
+## Global Styles
 
-对 Touying 而言，全局样式即为需要应用到所有地方的 set rules 或 show rules，例如 `#set text(size: 20pt)`。
+For Touying, global styles refer to set rules or show rules that need to be applied everywhere, such as `#set text(size: 20pt)`.
 
-其中，Touying 的主题会封装一些自己的全局样式，他们会被放在 `#show: init` 中，例如 university 主题就封装了
+Themes in Touying encapsulate some of their own global styles, which are placed in `#show: init`. For example, the university theme encapsulates the following:
 
 ```typst
 self.methods.init = (self: none, body) => {
@@ -18,7 +18,7 @@ self.methods.init = (self: none, body) => {
 }
 ```
 
-如果你并非一个主题制作者，而只是想给你的 slides 添加一些自己的全局样式，你可以简单地将它们放在 `#show: init` 之后，以及 `#show: slides` 之前，例如 metropolis 主题就推荐你自行加入以下全局样式：
+If you are not a theme creator but want to add your own global styles to your slides, you can simply place them after `#show: init` and before `#show: slides`. For example, the metropolis theme recommends adding the following global styles:
 
 ```typst
 #let s = themes.metropolis.register(s, aspect-ratio: "16-9")
@@ -36,7 +36,7 @@ self.methods.init = (self: none, body) => {
 #show: slides
 ```
 
-但是注意，你不应该使用 `#set page(..)`，而是应该修改 `s.page-args` 和 `s.padding`，例如
+However, note that you should not use `#set page(..)`. Instead, modify `s.page-args` and `s.padding`, for example:
 
 ```typst
 #(s.page-args += (
@@ -49,12 +49,11 @@ self.methods.init = (self: none, body) => {
 #(s.padding += (x: 4em, y: 0em))
 ```
 
+## Global Information
 
-## 全局信息
+Like Beamer, Touying, through an OOP-style unified API design, can help you better maintain global information, allowing you to easily switch between different themes. Global information is a typical example of this.
 
-就像 Beamer 一样，Touying 通过 OOP 风格的统一 API 设计，能够帮助您更好地维护全局信息，让您可以方便地在不同的主题之间切换，全局信息就是一个很典型的例子。
-
-你可以通过
+You can set the title, subtitle, author, date, and institution information for slides using:
 
 ```typst
 #let s = (s.methods.info)(
@@ -67,27 +66,29 @@ self.methods.init = (self: none, body) => {
 )
 ```
 
-分别设置 slides 的标题、副标题、作者、日期和机构信息。在后续，你就可以通过 `s.info` 或 `self.info` 这样的方式访问它们。
+In subsequent slides, you can access them through `s.info` or `self.info`.
 
-这些信息一般会在主题的 `title-slide`、`header` 和 `footer` 被使用到，例如 `#let s = themes.metropolis.register(s, aspect-ratio: "16-9", footer: self => self.info.institution)`。
+This information is generally used in the title-slide, header, and footer of the theme, for example:
 
-其中 `date` 可以接收 `datetime` 格式和 `content` 格式，并且 `datetime` 格式的日期显示格式，可以通过
+```typst
+#let s = themes.metropolis.register(s, aspect-ratio: "16-9", footer: self => self.info.institution)
+```
+
+The `date` can accept `datetime` format or `content` format, and the display format for the `datetime` format can be changed using:
 
 ```typst
 #let s = (s.methods.datetime-format)(self: s, "[year]-[month]-[day]")
 ```
 
-的方式更改。
-
-:::tip[原理]
+:::tip[Principle]
 
-在这里，我们会稍微引入一点 Touying 的 OOP 概念。
+Here, we will introduce a bit of OOP concept in Touying.
 
-您应该知道，Typst 是一个支持增量渲染的排版语言，也就是说，Typst 会缓存之前的函数调用结果，这就要求 Typst 里只有纯函数，即无法改变外部变量的函数。因此我们很难真正意义上地像 LaTeX 那样修改一个全局变量。即使是使用 `state` 或 `counter`，也需要使用 `locate` 与回调函数来获取里面的值，且实际上这种方式会对性能有很大的影响。
+You should know that Typst is a typesetting language that supports incremental rendering, which means Typst caches the results of previous function calls. This requires that Typst consists of pure functions, meaning functions that do not change external variables. Thus, it is challenging to modify a global variable in the true sense, even with the use of `state` or `counter`. This would require the use of `locate` with callback functions to obtain the values inside, and this approach would have a significant impact on performance.
 
-Touying 并没有使用 `state` 和 `counter`，也没有违反 Typst 纯函数的原则，而是使用了一种巧妙的方式，并以面向对象风格的代码，维护了一个全局单例 `s`。在 Touying 中，一个对象指拥有自己的成员变量和方法的 Typst 字典，并且我们约定方法均有一个命名参数 `self` 用于传入对象自身，并且方法均放在 `.methods` 域里。有了这个理念，我们就不难写出更新 `info` 的方法了：
+Touying does not use `state` or `counter` and does not violate the principle of pure functions in Typst. Instead, it uses a clever approach in an object-oriented style, maintaining a global singleton `s`. In Touying, an object refers to a Typst dictionary with its own member variables and methods. We agree that methods all have a named parameter `self` for passing the object itself, and methods are placed in the `.methods` domain. With this concept, it becomes easier to write methods to update `info`:
 
-```
+```typst
 #let s = (
   info: (:),
   methods: (
@@ -104,17 +105,16 @@ Touying 并没有使用 `state` 和 `counter`，也没有违反 Typst 纯函数
 Title is #s.info.title
 ```
 
-这样，你也能够理解 `utils.methods()` 函数的用途了：将 `self` 绑定到 `s` 的所有方法上并返回，并通过解包语法简化后续的使用。
+Now you can understand the purpose of the `utils.methods()` function: to bind `self` to all methods of `s` and return it, simplifying the subsequent usage through unpacking syntax.
 
 ```typst
 #let (init, slides, alert) = utils.methods(s)
 ```
 :::
 
+## State Initialization
 
-## 状态初始化
-
-一般而言，上面的两种方式就已经足够用于加入全局设置了，但是仍然会有部分情况，我们需要初始化 counters 或 states。如果将这些代码放在 `#show: slides` 之前，就会创建一个空白页，这是我们不想看见的，因此这时候我们就可以使用 `s.methods.append-preamble` 方法。例如在使用 codly 包的时候：
+In general, the two ways mentioned above are sufficient for adding global settings. However, there are still situations where we need to initialize counters or states. If you place this code before `#show: slides`, a blank page will be created, which is something we don't want to see. In such cases, you can use the `s.methods.append-preamble` method. For example, when using the codly package:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -146,8 +146,7 @@ Title is #s.info.title
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/0be2fbaf-cc03-4776-932f-259503d5e23a)
 
-
-又或者是进行 Pdfpc 的配置的时候：
+Or when configuring Pdfpc:
 
 ```typst
 // Pdfpc configuration

diff --git a/docs/docs/integration/_category_.json b/docs/docs/integration/_category_.json
@@ -1,8 +1,8 @@
 {
-  "label": "第三方包集成",
+  "label": "Package Integration",
   "position": 8,
   "link": {
     "type": "generated-index",
-    "description": "让第三方包与 Touying 集成。"
+    "description": "Discover how to integrate third-party packages with Touying."
   }
 }
diff --git a/docs/docs/integration/cetz.md b/docs/docs/integration/cetz.md
@@ -4,11 +4,11 @@ sidebar_position: 2
 
 # CeTZ
 
-Touying 提供了 `touying-reducer`，它能为 cetz 与 fletcher 加入 `pause` 和 `meanwhile` 动画。
+Touying provides the `touying-reducer`, which adds `pause` and `meanwhile` animations to CeTZ and Fletcher.
 
-## 简单动画
+## Simple Animation
 
-一个例子：
+An example:
 
 ```typst
 #import "@preview/touying:0.3.1": *
@@ -71,9 +71,9 @@ Touying 提供了 `touying-reducer`，它能为 cetz 与 fletcher 加入 `pause`
 ![image](https://github.com/touying-typ/touying/assets/34951714/9ba71f54-2a5d-4144-996c-4a42833cc5cc)
 
 
-## only 与 uncover
+## only and uncover
 
-事实上，我们也可以在 cetz 内部使用 `only` 和 `uncover`，只是需要一点技巧：
+In fact, we can also use `only` and `uncover` within CeTZ, but it requires a bit of technique:
 
 ```typst
 #slide(repeat: 3, self => [

diff --git a/docs/docs/integration/codly.md b/docs/docs/integration/codly.md
@@ -4,7 +4,7 @@ sidebar_position: 4
 
 # Codly
 
-在使用 codly 的时候，我们应该使用 `s.methods.append-preamble` 方法进行初始化。
+When using Codly, we should initialize it using the `s.methods.append-preamble` method.
 
 ```typst
 #import "@preview/touying:0.3.1": *

diff --git a/docs/docs/integration/fletcher.md b/docs/docs/integration/fletcher.md
@@ -4,9 +4,9 @@ sidebar_position: 3
 
 # Fletcher
 
-Touying 提供了 `touying-reducer`，它能为 fletcher 加入 `pause` 和 `meanwhile` 动画。
+Touying provides the `touying-reducer`, which adds `pause` and `meanwhile` animations to Fletcher.
 
-一个例子：
+An example:
 
 ```typst
 #import "@preview/touying:0.3.1": *

diff --git a/docs/docs/integration/pinit.md b/docs/docs/integration/pinit.md
@@ -4,9 +4,9 @@ sidebar_position: 1
 
 # Pinit
 
-[Pinit](https://github.com/OrangeX4/typst-pinit/) 包其提供了一个基于页面绝对定位与基于「图钉」pins 相对定位的能力，可以很方便地为 slides 实现箭头指示与解释说明的效果。
+[Pinit](https://github.com/OrangeX4/typst-pinit/) package provides the ability to perform absolute positioning based on the page and relative positioning based on "pins," making it convenient to implement arrow pointing and explanatory effects for slides.
 
-## 简单示例
+## Simple Example
 
 ```typst
 #import "@preview/pinit:0.1.3": *
@@ -22,18 +22,16 @@ A simple #pin(1)highlighted text#pin(2).
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/b17f9b80-5a8b-4943-a222-bcb0eb38611d)
 
-另一个 [示例](https://github.com/OrangeX4/typst-pinit/blob/main/examples/equation-desc.typ)：
+Another [example](https://github.com/OrangeX4/typst-pinit/blob/main/examples/equation-desc.typ):
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/9b4a6b50-fcfd-497d-9649-ae1f7762ee3f)
 
 
-
-## 复杂示例
+## Complex Example
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/7fb0095a-fd86-49ec-af95-15bc81a341c2)
 
-
-一个与 Touying 共同使用的示例：
+An example of shared usage with Touying:
 
 ```typst
 #import "@preview/touying:0.3.1": *

diff --git a/docs/docs/integration/polylux.md b/docs/docs/integration/polylux.md
@@ -4,18 +4,18 @@ sidebar_position: 5
 
 # Polylux
 
-借助 Touying 与 Polylux 的兼容性，你可以让 Polylux 也支持直接导出，只需要在你的 Polylux 源代码中加入下面的代码即可。
+With the compatibility between Touying and Polylux, you can make Polylux support direct export as well. Just add the following code to your Polylux source code:
 
-```
+```typst
 #import "@preview/touying:0.3.1"
 
 #locate(loc => touying.pdfpc.pdfpc-file(loc))
 ```
 
-假设你的文档为 `./example.typ`，则你可以通过
+Assuming your document is `./example.typ`, you can then export the `.pdfpc` file directly using the following command:
 
 ```sh
 typst query --root . ./example.typ --field value --one "<pdfpc-file>" > ./example.pdfpc
 ```
 
-直接导出 `.pdfpc` 文件，而不需要使用额外的 `polylux2pdfpc` 程序。
+This eliminates the need for an additional `polylux2pdfpc` program.