From 677613641cf6174fbb5938a73e36f6d8453eeaba Mon Sep 17 00:00:00 2001 From: OrangeX4 <318483724@qq.com> Date: Mon, 2 Sep 2024 04:21:16 +0800 Subject: [PATCH] docs: update changelog and README --- README.md | 91 +++++++++++++++------------------- changelog.md | 113 +++++++++++++++++++++---------------------- examples/example.typ | 2 +- 3 files changed, 96 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 3f1e37bd1..d23c81074 100644 --- a/README.md +++ b/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 "" > ./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 -// 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) diff --git a/changelog.md b/changelog.md index 03a510c3c..80c24e029 100644 --- a/changelog.md +++ b/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 `` 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(