docs: version 0.3.x

docs/i18n/zh/docusaurus-plugin-content-docs/version-0.3.x/changelog.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 14
+---
+
+# 更新日志
+
+## v0.3.1
+
+- fix some typos
+- fix slide-level bug
+- fix bug of pdfpc label
+
+
+## v0.3.0
+
+### Features
+
+- better show-slides mode.
+- support align and pad.
+
+### Documentation
+
+- Add more detailed documentation.
+
+### Refactor
+
+- simplify theme.
+
+### Fix
+
+- fix many bugs.
+
+## v0.2.1
+
+### Features
+
+- **Touying-reducer**: support cetz and fletcher animation
+- **university theme**: add university theme
+
+### Fix
+
+- fix footer progress in metropolis theme
+- fix some bugs in simple and dewdrop themes
+- fix bug that outline does not display more than 4 sections
+
+
+## v0.2.0
+
+- **Object-oriented programming:** Singleton `s`, binding methods `utils.methods(s)` and `(self: obj, ..) => {..}` methods.
+- **Page arguments management:** Instead of using `#set page(..)`, you should use `self.page-args` to retrieve or set page parameters, thereby avoiding unnecessary creation of new pages.
+- **`#pause` for sequence content:** You can use #pause at the outermost level of a slide, including inline and list.
+- **`#pause` for layout functions:** You can use the `composer` parameter to add yourself layout function like `utils.side-by-side`, and simply use multiple pos parameters like `#slide[..][..]`.
+- **`#meanwhile` for synchronous display:** Provide a `#meanwhile` for resetting subslides counter.
+- **`#pause` and `#meanwhile` for math equation:** Provide a `#touying-equation("x + y pause + z")` for math equation animations.
+- **Slides:** Create simple slides using standard headings.
+- **Callback-style `uncover`, `only` and `alternatives`:** Based on the concise syntax provided by Polylux, allow precise control of the timing for displaying content.
+  - You should manually control the number of subslides using the `repeat` parameter.
+- **Transparent cover:** Enable transparent cover using oop syntax like `#let s = (s.methods.enable-transparent-cover)(self: s)`.
+- **Handout mode:** enable handout mode by `#let s = (s.methods.enable-handout-mode)(self: s)`.
+- **Fit-to-width and fit-to-height:** Fit-to-width for title in header and fit-to-height for image.
+  - `utils.fit-to-width(grow: true, shrink: true, width, body)`
+  - `utils.fit-to-height(width: none, prescale-width: none, grow: true, shrink: true, height, body)`
+- **Slides counter:** `states.slide-counter.display() + " / " + states.last-slide-number` and `states.touying-progress(ratio => ..)`.
+- **Appendix:** Freeze the `last-slide-number` to prevent the slide number from increasing further.
+- **Sections:** Touying's built-in section support can be used to display the current section title and show progress.
+  - `section` and `subsection` parameter in `#slide` to register a new section or subsection.
+  - `states.current-section-title` to get the current section.
+  - `states.touying-outline` or `s.methods.touying-outline` to display a outline of sections.
+  - `states.touying-final-sections(sections => ..)` for custom outline display.
+  - `states.touying-progress-with-sections((current-sections: .., final-sections: .., current-slide-number: .., last-slide-number: ..) => ..)` for powerful progress display.
+- **Navigation bar**: Navigation bar like [here](https://github.com/zbowang/BeamerTheme) by `states.touying-progress-with-sections(..)`, in `dewdrop` theme.
+- **Pdfpc:** pdfpc support and export `.pdfpc` file without external tool by `typst query` command simply.

docs/i18n/zh/docusaurus-plugin-content-docs/version-0.3.x/code-styles.md

@@ -0,0 +1,169 @@
+---
+sidebar_position: 4
+---
+
+# 代码风格
+
+## 简单风格
+
+如果我们只是需要简单使用，我们可以直接在标题下输入内容，就像是在编写正常 Typst 文档一样。这里的标题有着分割页面的作用，同时我们也能正常地使用 `#pause` 等命令实现动画效果。
+
+```typst
+#import "@preview/touying:0.3.1": *
+
+#let s = themes.simple.register(s)
+#let (init, slides) = utils.methods(s)
+#show: init
+
+#let (slide,) = utils.slides(s)
+#show: slides
+
+= Title
+
+== First Slide
+
+Hello, Touying!
+
+#pause
+
+Hello, Typst!
+```
+
+![image](https://github.com/touying-typ/touying/assets/34951714/f5bdbf8f-7bf9-45fd-9923-0fa5d66450b2)
+
+并且你可以使用空标题 `==` 创建一个新页，这个技巧也有助于清除上一个标题的继续应用。
+
+PS：我们可以使用 `#slides-end` 记号来标志 `#show: slides` 的结束。
+
+
+## 块风格
+
+很多时候，仅仅使用简单风格并不能实现我们需要的所有功能，为了更强大的功能和更清晰的结构，我们同样可以使用 `#slide[...]` 形式的块风格，其中 `#slide` 函数需要使用 `#let (slide,) = utils.slides(s)` 语法进行解包，才能正常在 `#show: slides` 后使用。
+
+例如上面的例子就可以改造成
+
+```typst
+#import "@preview/touying:0.3.1": *
+
+#let s = themes.simple.register(s)
+#let (init, slides) = utils.methods(s)
+#show: init
+
+#let (slide,) = utils.slides(s)
+#show: slides
+
+= Title
+
+== First Slide
+
+#slide[
+  Hello, Touying!
+
+  #pause
+
+  Hello, Typst!
+]
+```
+
+这样做的好处有很多：
+
+1. 很多时候，我们不只是需要默认的 `#slide[...]`，还需要 `#focus-slide[...]` 这些特殊的 `slide` 函数；
+2. 不同主题的 `#slide[...]` 函数可能有比默认更多的参数，例如 university 主题的 `#slide[...]` 函数就会有着 `subtitle` 参数；
+3. 只有 `slide` 函数才可以通过回调风格的内容块来使用 `#only` 和 `#uncover` 函数实现复杂的动画效果。
+4. 能有着更清晰的结构，通过辨别 `#slide[...]` 块，我们可以很容易地分辨出 slides 的具体分页效果。
+
+
+## 约定优于配置
+
+你可能注意到了，在使用 simple 主题时，我们使用一级标题会自动创建一个 section slide，这是因为 simple 主题注册了一个 `s.methods.touying-new-section-slide` 方法，因此 touying 会默认调用这个方法。
+
+如果我们不希望它自动创建这样一个 section slide，我们可以将这个方法删除：
+
+```typst
+#import "@preview/touying:0.3.1": *
+
+#let s = themes.simple.register(s)
+#(s.methods.touying-new-section-slide = none)
+#let (init, slides) = utils.methods(s)
+#show: init
+
+#let (slide,) = utils.slides(s)
+#show: slides
+
+= Title
+
+== First Slide
+
+Hello, Touying!
+
+#pause
+
+Hello, Typst!
+```
+
+![image](https://github.com/touying-typ/touying/assets/34951714/17a89a59-9491-4e1f-95c0-09a22105ab35)
+
+如你所见，这样就只会剩下两页，而默认的 section slide 就会消失了。
+
+同理，我们也可以注册一个新的 section slide：
+
+```typst
+#import "@preview/touying:0.3.1": *
+
+#let s = themes.simple.register(s)
+#(s.methods.touying-new-section-slide = (self: none, section, ..args) => {
+  self = utils.empty-page(self)
+  (s.methods.touying-slide)(self: self, section: section, {
+    set align(center + horizon)
+    set text(size: 2em, fill: s.colors.primary, style: "italic", weight: "bold")
+    section
+  }, ..args)
+})
+#let (init, slides, touying-outline) = utils.methods(s)
+#show: init
+
+#let (slide,) = utils.slides(s)
+#show: slides
+
+= Title
+
+== First Slide
+
+Hello, Touying!
+
+#pause
+
+Hello, Typst!
+```
+
+![image](https://github.com/touying-typ/touying/assets/34951714/5305efda-0cd4-42eb-9f2e-89abc30b6ca2)
+
+同样地，我们也可以修改 `s.methods.touying-new-subsection-slide` 来对 `subsection` 做同样的事。
+
+实际上，除了 `s.methods.touying-new-section-slide`，另一个特殊的 `slide` 函数就是 `s.methods.slide` 函数，它会在简单风格里没有显示使用 `#slide[...]` 的情况下默认被调用。
+
+同时，由于 `#slide[...]` 被注册在了 `s.slides = ("slide",)` 里，因此 `section`，`subsection` 和 `title` 参数会被自动传入，而其他的如 `#focus-slide[...]` 则不会自动传入这三个参数。
+
+:::tip[原理]
+
+实际上，你也可以不使用 `#show: slides` 和 `utils.slides(s)`，而是只使用 `utils.methods(s)`，例如
+
+```typst
+#import "@preview/touying:0.3.1": *
+
+#let s = themes.simple.register(s)
+#let (init, touying-outline, slide) = utils.methods(s)
+#show: init
+
+#slide(section: [Title], title: [First Slide])[
+  Hello, Touying!
+
+  #pause
+
+  Hello, Typst!
+]
+```
+
+这时候需要手动传入 `section`、`subsection` 和 `title`，但是会有更好的性能，适合需要更快的性能的情况，例如超过数十数百页的情形。
+
+:::

docs/i18n/zh/docusaurus-plugin-content-docs/version-0.3.x/dynamic/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "动态幻灯片",
+  "position": 7,
+  "link": {
+    "type": "generated-index",
+    "description": "想要在 PDF 中创建动画，我们就需要为同一个 slide 创建多个略有不同的页面，以便通过切换页面的方式实现动画，我们称这些页面为 subslides。"
+  }
+}

docs/i18n/zh/docusaurus-plugin-content-docs/version-0.3.x/dynamic/complex.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 2
+---
+
+# 复杂动画
+
+得益于 [Polylux](https://polylux.dev/book/dynamic/syntax.html) 提供的语法，我们同样能够在 Touying 中使用 `only`、`uncover` 和 `alternatives`。
+
+
+## 回调风格的函数
+
+为了避免上文提到的 `styled` 与 `layout` 限制，Touying 利用回调函数巧妙实现了总是能生效的 `only`、`uncover` 和 `alternatives`，具体来说，您要这样引入这三个函数：
+
+```typst
+#slide(repeat: 3, self => [
+  #let (uncover, only, alternatives) = utils.methods(self)
+
+  In subslide #self.subslide,
+
+  test #uncover("2-")[uncover] function,
+
+  and test #only("2-")[only] function,
+
+  #pause
+
+  and paused text.
+])
+```
+
+![image](https://github.com/touying-typ/touying/assets/34951714/e9a6b8c5-daf0-4cf2-8d39-1a768ce1dfea)
+
+注意到了吗？我们不再是传入一个内容块，而是传入了一个参数为 `self` 的回调函数，随后我们通过
+
+```typst
+#let (uncover, only, alternatives) = utils.methods(self)
+```
+
+从 `self` 中取出了 `only`、`uncover` 和 `alternatives` 这三个函数，并在后续调用它们。
+
+这里还有一些有趣的事实，例如 int 类型的 `self.subslide` 指示了当前 subslide 索引，而实际上 `only`、`uncover` 和 `alternatives` 函数也正是依赖 `self.subslide` 实现的获取当前 subslide 索引。
+
+:::warning[警告]
+
+我们手动指定了参数 `repeat: 3`，这代表着显示 3 张 subslides，我们需要手动指定是因为 Touying 无法探知 `only`、`uncover` 和 `alternatives` 需要显示多少张 subslides。
+
+:::
+
+## only
+
+`only` 函数表示只在选定的 subslides 中「出现」，如果不出现，则会完全消失，也不会占据任何空间。也即 `#only(index, body)` 要么为 `body` 要么为 `none`。
+
+其中 index 可以是 int 类型，也可以是 `"2-"` 或 `"2-3"` 这样的 str 类型，更多用法可以参考 [Polylux](https://polylux.dev/book/dynamic/complex.html)。
+
+
+## uncover
+
+`uncover` 函数表示只在选定的 subslides 中「显示」，否则会被 `cover` 函数遮挡，但仍会占据原有。也即 `#uncover(index, body)` 要么为 `body` 要么为 `cover(body)`。
+
+其中 index 可以是 int 类型，也可以是 `"2-"` 或 `"2-3"` 这样的 str 类型，更多用法可以参考 [Polylux](https://polylux.dev/book/dynamic/complex.html)。
+
+您应该也注意到了，事实上 `#pause` 也使用了 `cover` 函数，只是提供了更便利的写法，实际上它们的效果基本上是一致的。
+
+
+## alternatives
+
+`alternatives` 函数表示在不同的 subslides 中展示一系列不同的内容，例如
+
+```typst
+#slide(repeat: 3, self => [
+  #let (uncover, only, alternatives) = utils.methods(self)
+
+  #alternatives[Ann][Bob][Christopher]
+  likes
+  #alternatives[chocolate][strawberry][vanilla]
+  ice cream.
+])
+```
+
+![image](https://github.com/touying-typ/touying/assets/34951714/392707ea-0bcd-426b-b232-5bc63b9a13a3)
+
+如你所见，`alternatives` 能够自动撑开到最合适的宽度和高度，这是 `only` 和 `uncover` 所没有的能力。事实上 `alternatives` 还有着其他参数，例如 `start: 2`、`repeat-last: true` 和 `position: center + horizon` 等，更多用法可以参考 [Polylux](https://polylux.dev/book/dynamic/alternatives.html)。
+