docs: update changelog and README

README.md

@@ -2,7 +2,7 @@
 
 [Touying](https://github.com/touying-typ/touying) (投影 in chinese, /tóuyǐng/, meaning projection) is a powerful and efficient package for creating presentation slides in Typst. Partial code is inherited from [Polylux](https://github.com/andreasKroepelin/polylux). Therefore, many concepts and APIs remain consistent with Polylux.
 
-Touying provides an object-oriented programming (OOP) style syntax, allowing the simulation of "global variables" through a global singleton, which makes it easy to write themes for Touying. Touying does not rely on `counter` and `locate` to implement `#pause`, resulting in better performance.
+Touying provides automatically injected global configurations. Besides, Touying does not rely on `counter` and `locate` to implement `#pause`, resulting in better performance.
 
 If you like it, consider [giving a star on GitHub](https://github.com/touying-typ/touying). Touying is a community-driven project, feel free to suggest any ideas and contribute.
 
@@ -99,14 +99,10 @@ Before you begin, make sure you have installed the Typst environment. If not, yo
 To use Touying, you only need to include the following code in your document:
 
 ```typst
-#import "@preview/touying:0.4.2": *
+#import "@preview/touying:0.5.0": *
+#import themes.simple: *
 
-#let s = themes.simple.register(aspect-ratio: "16-9")
-#let (init, slides) = utils.methods(s)
-#show: init
-
-#let (slide, empty-slide) = utils.slides(s)
-#show: slides
+#show: simple-theme.with(aspect-ratio: "16-9")
 
 = Title
 
@@ -131,38 +127,20 @@ It's simple. Congratulations on creating your first Touying slide! 🎉
 In fact, Touying provides various styles for writing slides. For example, the above example uses first-level and second-level titles to create new slides. However, you can also use the `#slide[..]` format to access more powerful features provided by Touying.
 
 ```typst
-#import "@preview/touying:0.4.2": *
+#import "@preview/touying:0.5.0": *
+#import themes.university: *
 #import "@preview/cetz:0.2.2"
-#import "@preview/fletcher:0.4.4" as fletcher: node, edge
+#import "@preview/fletcher:0.5.1" as fletcher: node, edge
 #import "@preview/ctheorems:1.1.2": *
+#import "@preview/numbly:0.1.0": numbly
 
 // cetz and fletcher bindings for touying
 #let cetz-canvas = touying-reducer.with(reduce: cetz.canvas, cover: cetz.draw.hide.with(bounds: true))
 #let fletcher-diagram = touying-reducer.with(reduce: fletcher.diagram, cover: fletcher.hide)
 
-// Register university theme
-// You can replace it with other themes and it can still work normally
-#let s = themes.university.register(aspect-ratio: "16-9")
-
-// Set the numbering of section and subsection
-#let s = (s.methods.numbering)(self: s, section: "1.", "1.1")
-
-// Set the speaker notes configuration
-// #let s = (s.methods.show-notes-on-second-screen)(self: s, right)
-
-// Global information configuration
-#let s = (s.methods.info)(
-  self: s,
-  title: [Title],
-  subtitle: [Subtitle],
-  author: [Authors],
-  date: datetime.today(),
-  institution: [Institution],
-)
-
 // Pdfpc configuration
 // typst query --root . ./example.typ --field value --one "<pdfpc-file>" > ./example.pdfpc
-#let s = (s.methods.append-preamble)(self: s, pdfpc.config(
+#pdfpc.config(
   duration-minutes: 30,
   start-time: datetime(hour: 14, minute: 10, second: 0),
   end-time: datetime(hour: 14, minute: 40, second: 0),
@@ -176,7 +154,7 @@ In fact, Touying provides various styles for writing slides. For example, the ab
     alignment: "vertical",
     direction: "inward",
   ),
-))
+)
 
 // Theorems configuration by ctheorems
 #show: thmrules.with(qed-symbol: $square$)
@@ -191,15 +169,26 @@ In fact, Touying provides various styles for writing slides. For example, the ab
 #let example = thmplain("example", "Example").with(numbering: none)
 #let proof = thmproof("proof", "Proof")
 
-// Extract methods
-#let (init, slides, touying-outline, alert, speaker-note) = utils.methods(s)
-#show: init
+#show: university-theme.with(
+  aspect-ratio: "16-9",
+  // config-common(handout: true),
+  config-info(
+    title: [Title],
+    subtitle: [Subtitle],
+    author: [Authors],
+    date: datetime.today(),
+    institution: [Institution],
+    logo: emoji.school,
+  ),
+)
+
+#set heading(numbering: numbly("{1}.", default: "1.1"))
+
+#title-slide()
 
-#show strong: alert
+== Outline <touying:hidden>
 
-// Extract slide functions
-#let (slide, empty-slide) = utils.slides(s)
-#show: slides
+#components.adaptive-columns(outline(title: none, indent: 1em))
 
 = Animation
 
@@ -221,9 +210,9 @@ Meanwhile, #pause we can also use `#meanwhile` to #pause display other content s
 ]
 
 
-== Complex Animation - Mark-Style
+== Complex Animation
 
-At subslide #utils.touying-wrapper((self: none) => str(self.subslide)), we can
+At subslide #touying-fn-wrapper((self: none) => str(self.subslide)), we can
 
 use #uncover("2-")[`#uncover` function] for reserving space,
 
@@ -232,7 +221,7 @@ use #only("2-")[`#only` function] for not reserving space,
 #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
 
 
-== Complex Animation - Callback-Style
+== Callback Style Animation
 
 #slide(repeat: 3, self => [
   #let (uncover, only, alternatives) = utils.methods(self)
@@ -249,12 +238,12 @@ use #only("2-")[`#only` function] for not reserving space,
 
 == Math Equation Animation
 
-Touying equation with `pause`:
+Equation with `pause`:
 
-#touying-equation(`
+$
   f(x) &= pause x^2 + 2x + 1  \
-        &= pause (x + 1)^2  \
-`)
+       &= pause (x + 1)^2  \
+$
 
 #meanwhile
 
@@ -365,15 +354,13 @@ Fletcher Animation in Touying:
 #lorem(200)
 
 
-// appendix by freezing last-slide-number
-#let s = (s.methods.appendix)(self: s)
-#let (slide, empty-slide) = utils.slides(s)
+#show: appendix
+
+= Appendix
 
 == Appendix
 
-#slide[
-  Please pay attention to the current slide number.
-]
+Please pay attention to the current slide number.
 ```
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/5ac2b11c-9e77-4389-ade6-682c9fc3e1fb)

changelog.md

@@ -2,20 +2,20 @@
 
 ## v0.5.0
 
-这一个重大的破坏性版本更新。Touying 去除了许多错误决策下的历史包袱，重新设计了许多功能。这个版本的目标是让 Touying 更加易用，更加灵活，更加强大。
+This is a significant disruptive version update. Touying has removed many mistakes that resulted from incorrect decisions. We have redesigned numerous features. The goal of this version is to make Touying more user-friendly, more flexible, and more powerful.
 
-**重大的变化包括：**
+**Major changes include:**
 
-- 避免闭包和 OOP 语法，这样做的优势在于让 Touying 的配置更加简单，且可以使用 document comments 为 slide 函数提供更多的自动补全信息。
-  - 原有的 `#let slide(self: none, ..args) = { .. }` 现在变为了 `#let slide(..args) = touying-slide-wrapper(self => { .. })`，其中 `self` 会被自动注入。
-  - 我们可以使用 `config-xxx` 语法来配置 Touying，例如 `#show: university-theme.with(aspect-ratio: "16-9", config-colors(primary: blue))`。
-- `touying-slide` 函数不再包含 `section`、`subsection` 和 `title` 参数，这些参数会被作为 `self.headings` 以不可见的 1，2 或 3 级等 heading（可以通过 slide-level 配置）自动插入到 slide 页面中。
-  - 我们可以利用 Typst 提供的强大的 heading 来支持 numbering、outline 和 bookmark 等功能。
-  - 在 `#slide[= XXX]` 这样 slide 函数内部的 heading 会通过 offset 参数将其变为 `slide-level + 1` 级的 heading。
-  - 我们可以利用 heading 的 label 来控制很多东西，例如支持 `touying:hidden` 等特殊 label，或者实现 short heading，亦或者实现 `#touying-recall()` 再现某个 slide。
-- Touying 现在支持在任意位置正常地使用 set 和 show 规则，而不再需要在特定位置使用。
+- Avoiding closures and OOP syntax, which makes Touying's configuration simpler and allows for the use of document comments to provide more auto-completion information for the slide function.
+  - The existing `#let slide(self: none, ..args) = { .. }` is now `#let slide(..args) = touying-slide-wrapper(self => { .. })`, where `self` is automatically injected.
+  - We can use `config-xxx` syntax to configure Touying, for example, `#show: university-theme.with(aspect-ratio: "16-9", config-colors(primary: blue))`.
+- The `touying-slide` function no longer includes parameters like `section`, `subsection`, and `title`. These will be automatically inserted into the slide as invisible level 1, 2, or 3 headings via `self.headings` (controlled by the `slide-level` configuration).
+  - We can leverage the powerful headings provided by Typst to support numbering, outlines, and bookmarks.
+  - Headings within the `#slide[= XXX]` function will be adjusted to level `slide-level + 1` using the `offset` parameter.
+  - We can use labels on headings to control many aspects, such as supporting  the `<touying:hidden>` and other special labels, implementing short headings, or recalling a slide with `#touying-recall()`.
+- Touying now supports the normal use of `set` and `show` rules at any position, without requiring them to be in specific locations.
 
-一个简单的使用例子如下，更多的示例可以在 `examples` 目录下找到：
+A simple usage example is shown below, and more examples can be found in the `examples` directory:
 
 ```typst
 #import "@preview/touying:0.5.0": *
@@ -44,52 +44,51 @@
 #lorem(40)
 ```
 
-**主题迁移指南：**
-
-可以到 `themes` 目录下查看具体主题的变化。大体来说，如果你想迁移已有的主题，你应该：
-
-1. 将 `register` 函数重命名为 `xxx-theme`，并去除 `self` 参数。
-2. 添加一个 `show: touying-slides.with(..)` 的配置。
-  1. 将原有的 `self.methods.colors` 更改为 `config-colors(primary: rgb("#xxxxxx"))`。
-  2. 将原有的 `self.page-args` 更改为 `config-page()`。
-  3. 将原有的 `self.methods.slide = slide` 更改为 `config-methods(slide: slide)`
-  4. 将原有的 `self.methods.new-section-slide = new-section-slide` 更改为 `config-methods(new-section-slide: new-section-slide)`
-  5. 将原有的 `self.xxx-footer` 这样的主题私有变量更改为 `config-store(footer: [..])`，后续你可以通过 `self.store.footer` 来获取。
-  6. 将原有的 `header` 和 `footer` 移到 `slide` 函数中配置，而不是在 `xxx-theme` 函数中配置。
-  7. 你可以在 `xxx-theme` 中直接使用 set 或 show 规则，或者也可以通过 `config-methods(init: (self: none, body) => { .. })` 来配置，这样你能充分利用 `self` 参数。
-3. 对于 `states.current-section-with-numbering`，你可以使用 `utils.display-current-heading(level: 1)` 来代替。
-  1. 如果你仅要获取上一个标题，无所谓是 section 还是 subsection，你可以使用 `utils.display-previous-heading()` 来代替。
-4. `alert` 函数可以通过 `config-methods(alert: utils.alert-with-primary-color)` 来代替。
-5. 我们不再需要 `touying-outline()` 函数，你可以直接使用 `components.adaptive-columns(outline())` 来代替。或者考虑使用 `components.progressive-outline()` 或 `components.custom-progressive-outline()`。
-6. 将 `context states.slide-counter.display() + " / " + states.last-slide-number` 替换为 `context utils.slide-counter.display() + " / " + utils.last-slide-number`。即我们不再使用 `states`，而是使用 `utils`。
-7. 删除 `slides` 函数，我们不再需要这个函数。因为我们不应该隐式注入 `title-slide()`，而是应该显式地使用 `#title-slide()`。如果你实在需要，你可以考虑在 `xxx-theme` 函数中加入。
-8. 将原来的 `#let slide(self: none, ..args) = { .. }` 变为了 `#let slide(..args) = touying-slide-wrapper(self => { .. })`。其中 `self` 会被自动注入。
-  1. 将具体的参数配置更改为 `self = utils.merge-dicts(self, config-page(fill: self.colors.neutral-lightest))` 方式。
-  2. 去除 `self = utils.empty-page(self)`，你可以使用 `config-common(freeze-slide-counter: true)` 和 `config-page(margin: 0em)` 来代替。
-  3. 将 `(self.methods.touying-slide)()` 更改为 `touying-slide()`。
-9. 你可以通过配置 `config-common(subslide-preamble: self => text(1.2em, weight: "bold", utils.display-current-heading(depth: self.slide-level)))` 来实现给 slide 插入可视的 heading。
-10. 最后，别忘了给你的函数们加上 document comments，这样你的用户就能获得更好的自动补全提示，尤其是在使用 Tinymist 插件时。
-
-
-**其他变化：**
-
-- feat: 实现了 fake frozen states support，你现在可以正常地使用 `numbering` 和 `#pause`。这个行为可以通过 `config-common()` 里的 `enable-frozen-states-and-counters`，`frozen-states` 和 `frozen-counters` 控制。
-- feat: 实现了 `label-only-on-last-subslide` 功能，可以让 `@equation` 和 `@figure` 在有 `#pause` 动画的情况下正在工作，避免非 unique label 警告。
-- feat: 添加了 `touying-recall(<label>)` 函数，用于重现某个 slide。
-- feat: 实现了 `nontight-list-enum-and-terms` 功能，默认开启。强制让 list, enum 和 terms 的 `tight` 参数为 `false`。你可以通过 `#set list(spacing: 1em)` 来控制间距大小。
-- feat: 将 `list` 替换为 `terms` 实现，以实现 `align-list-marker-with-baseline`，默认关闭。 
-- feat: 实现了 `scale-list-items` 功能，`scale-list-items: 0.8` will scale the list items by 0.8.
-- feat: 支持直接在数学公式里使用 `#pause` 和 `#meanwhile`，如 `$x + pause y$`。
-- feat: 为大部分布局函数实现了 `#pause` 和 `#meanwhile` 支持，如 grid 和 table 函数。
-- feat: 添加了 `#show: appendix` 支持，其本质是 `#show: touying-set-config.with((appendix: true))`。
-- feat: 加入了 `<touying:hidden>`, `<touying:unnumbered>`, `<touying:unoutlined>`, `<touying:unbookmarked>` 特殊 label，用于更简单地控制 heading 的行为。
-- feat: 加入简易的 `utils.short-heading` 支持，可以用 label 来实现 short-heading，例如将 `<sec:my-section>` 显示为 `My Section`。
-- feat: 加入了 `#components.adaptive-columns()`，实现尽量占据一个页面的 adaptive columns。通常与 `outline()` 函数一起使用。
-- feat: 加入了 `#show: magic.bibliography-as-footnote.with(bibliography("ref.bib"))`，可以让 bibliography 在 footnote 中显示。
-- feat: 加入了 `custom-progressive-outline`, `mini-slides` 等 components。
-- feat: 删除 `touying-outline()`，你可以直接使用 `outline()`。
-- fix: 更换了未来可能会不兼容的代码，例如 `type(s) == "string"` 和 `locate(loc => { .. })` 等。
-- fix: 修复了一些 bugs。
+**Theme Migration Guide:**
+
+For detailed changes to specific themes, you can refer to the `themes` directory. Generally, if you want to migrate an existing theme, you should:
+
+1. Rename the `register` function to `xxx-theme` and remove the `self` parameter.
+2. Add a `show: touying-slides.with(..)` configuration.
+   - Change `self.methods.colors` to `config-colors(primary: rgb("#xxxxxx"))`.
+   - Change `self.page-args` to `config-page()`.
+   - Change `self.methods.slide = slide` to `config-methods(slide: slide)`.
+   - Change `self.methods.new-section-slide = new-section-slide` to `config-methods(new-section-slide: new-section-slide)`.
+   - Change private theme variables like `self.xxx-footer` to `config-store(footer: [..])`, which you can access through `self.store.footer`.
+   - Move the configuration of headers and footers into the `slide` function rather than in the `xxx-theme` function.
+   - You can directly use `set` or `show` rules in `xxx-theme` or configure them through `config-methods(init: (self: none, body) => { .. })` to fully utilize the `self` parameter.
+3. For `states.current-section-with-numbering`, you can use `utils.display-current-heading(level: 1)` instead.
+   - If you only need the previous heading regardless of whether it is a section or a subsection, use `utils.display-current-heading()`.
+4. The `alert` function can be replaced with `config-methods(alert: utils.alert-with-primary-color)`.
+5. The `touying-outline()` function is no longer needed; you can use `components.adaptive-columns(outline())` instead. Consider using `components.progressive-outline()` or `components.custom-progressive-outline()`.
+6. Replace `states.slide-counter.display() + " / " + states.last-slide-number` with `context utils.slide-counter.display() + " / " + utils.last-slide-number`. That is, we no longer use `states` but `utils`.
+7. Remove the `slides` function; we no longer need this function. Instead of implicitly injecting `title-slide()`, explicitly use `#title-slide()`. If necessary, consider adding it in the `xxx-theme` function.
+8. Change `#let slide(self: none, ..args) = { .. }` to `#let slide(..args) = touying-slide-wrapper(self => { .. })`, where `self` is automatically injected.
+   - Change specific parameter configurations to `self = utils.merge-dicts(self, config-page(fill: self.colors.neutral-lightest))`.
+   - Remove `self = utils.empty-page(self)` and use `config-common(freeze-slide-counter: true)` and `config-page(margin: 0em)` instead.
+   - Change `(self.methods.touying-slide)()` to `touying-slide()`.
+9. You can insert visible headings into slides by configuring `config-common(subslide-preamble: self => text(1.2em, weight: "bold", utils.display-current-heading(depth: self.slide-level)))`.
+10. Finally, don't forget to add document comments to your functions so your users can get better auto-completion hints, especially when using the Tinymist plugin.
+
+**Other Changes:**
+
+- feat: implemented fake frozen states support, allowing you to use numbering and `#pause` normally. This behavior can be controlled with `enable-frozen-states-and-counters`, `frozen-states`, and `frozen-counters` in `config-common()`.
+- feat: implemented `label-only-on-last-subslide` functionality to prevent non-unique label warnings when working with `@equation` and `@figure` in conjunction with `#pause` animations.
+- feat: added the `touying-recall(<label>)` function to replay a specific slide.
+- feat: implemented `nontight-list-enum-and-terms`, which defaults to `true` and forces `list`, `enum`, and `terms` to have their `tight` parameter set to `false`. You can control spacing size with `#set list(spacing: 1em)`.
+- feat: replaced `list` with `terms` implementation to achieve `align-list-marker-with-baseline`, which is off by default.
+- feat: implemented `scale-list-items`, scaling list items by a factor, e.g., `scale-list-items: 0.8` scales list items by 0.8.
+- feat: supported direct use of `#pause` and `#meanwhile` in math expressions, such as `$x + pause y$`.
+- feat: provided `#pause` and `#meanwhile` support for most layout functions, such as `grid` and `table`.
+- feat: added `#show: appendix` support, essentially equivalent to `#show: touying-set-config.with((appendix: true))`.
+- feat: Introduced special labels `<touying:hidden>`, `<touying:unnumbered>`, `<touying:unoutlined>`, `<touying:unbookmarked>` to simplify control over heading behavior.
+- feat: added basic `utils.short-heading` support to display short headings using labels, such as displaying `<sec:my-section>` as "My Section".
+- feat: added `#components.adaptive-columns()` to achieve adaptive columns that span a page, typically used with the `outline()` function.
+- feat: added `#show: magic.bibliography-as-footnote.with(bibliography("ref.bib"))` to display the bibliography in footnotes.
+- feat: added components like `custom-progressive-outline`, `mini-slides`.
+- feat: removed `touying-outline()`, which can be directly replaced with `outline()`.
+- fix: replaced potentially incompatible code, such as `type(s) == "string"` and `locate(loc => { .. })`.
+- fix: Fixed some bugs.
 
 
 ## v0.4.2

examples/example.typ

@@ -1,7 +1,7 @@
 #import "../lib.typ": *
 #import themes.university: *
 #import "@preview/cetz:0.2.2"
-#import "@preview/fletcher:0.4.4" as fletcher: node, edge
+#import "@preview/fletcher:0.5.1" as fletcher: node, edge
 #import "@preview/ctheorems:1.1.2": *
 #import "@preview/numbly:0.1.0": numbly