Merge pull request #81 from andreasKroepelin/main

Release v0.3.0

.github/workflows/mdbook.yml

@@ -7,7 +7,7 @@ name: Deploy mdBook site to Pages
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
+    branches: ["release"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

README.md

@@ -1,5 +1,8 @@
 # Polylux <img src="https://andreaskroepelin.github.io/polylux/book/logo.png" style="width: 3em;"></img>
 This is a package for creating presentation slides in [Typst](https://typst.app/).
+Read the [book](https://andreaskroepelin.github.io/polylux/book) to learn all
+about it and click [here](https://andreaskroepelin.github.io/polylux/book/changelog.html)
+to see what's new!
 
 If you like it, consider [giving a star on GitHub](https://github.com/andreasKroepelin/polylux)!
 
@@ -14,8 +17,8 @@ If you like it, consider [giving a star on GitHub](https://github.com/andreasKro
 ## Quickstart
 For the bare-bones, do-it-yourself experience, all you need is:
 ```typ
-// Get polylux from the official package repository
-#import "@preview/polylux:0.2.0": *
+// Get Polylux from the official package repository
+#import "@preview/polylux:0.3.0": *
 
 // Make the paper dimensions fit for a presentation and the text larger
 #set page(paper: "presentation-16-9")
@@ -54,7 +57,7 @@ or you can use one of the provided themes.
 The simplest one of them is called `simple` (what a coincidence!).
 It is still very unintrusive but gives you some sensible defaults:
 ```typ
-#import "@preview/polylux:0.2.0": *
+#import "@preview/polylux:0.3.0": *
 
 #import themes.simple: *
 
@@ -95,9 +98,8 @@ It is still very unintrusive but gives you some sensible defaults:
   == Dynamic slide
   Did you know that...
 
-  #uncover(2)[
-    ...you can see the current section at the top of the slide?
-  ]
+  #pause
+  ...you can see the current section at the top of the slide?
 ]
 ```
 This time, we obtain these PDF pages:
@@ -111,23 +113,30 @@ The book
 on how to use (and create your own) themes.
 
 
-For dynamic content, polylux also provides [a convenient API for complex
+For dynamic content, Polylux also provides [a convenient API for complex
 overlays](https://andreaskroepelin.github.io/polylux/book/dynamic/dynamic.html).
 
+If you use [pdfpc](https://pdfpc.github.io/) to display your slides, you can rely
+on [Polylux' support for it](https://andreaskroepelin.github.io/polylux/book/external/pdfpc.html)
+and create speaker notes, hide slides, configure the timer and more!
+
 Visit the
 [book](https://andreaskroepelin.github.io/polylux/book)
 for more details or take a look at the
 [demo PDF](https://github.com/andreasKroepelin/polylux/releases/latest/download/demo.pdf)
 where you can see the features of this template in action.
 
-**⚠ This package is under active development.
-While I try to make sure that the `main`-branch always is in a usable state,
-there are no compatibility guarantees!**
+**⚠ This package is under active development and there are no backwards
+compatibility guarantees!**
 
 ## Acknowledgements
 Thank you to...
 - [@drupol](https://github.com/drupol) for the `university` theme
 - [@Enivex](https://github.com/Enivex) for the `metropolis` theme
 - [@MarkBlyth](https://github.com/MarkBlyth) for contributing to the `clean` theme
-- [@fncnt](https://github.com/fncnt) for coming up with the name "polylux"
+- [@ntjess](https://github.com/ntjess) for contributing to the height fitting
+  feature
+- [@JuliusFreudenberger](https://github.com/JuliusFreudenberger) for maintaining
+  the `polylux2pdfpc` AUR package
+- [@fncnt](https://github.com/fncnt) for coming up with the name "Polylux"
 - the Typst authors and contributors for this refreshing piece of software

book/src/IMPORT.typ

@@ -0,0 +1 @@
+#import "@preview/polylux:0.3.0": *

book/src/SUMMARY.md

@@ -8,8 +8,8 @@
   - [General syntax](./dynamic/syntax.md)
   - [Complex rules](./dynamic/complex.md)
   - [Helper functions](./dynamic/helper.md)
-    - [one-by-one and line-by-line](./dynamic/obo-lbl.md)
     - [pause](./dynamic/pause.md)
+    - [one-by-one and friends](./dynamic/obo-lbl.md)
     - [alternatives](./dynamic/alternatives.md)
   - [Cover mode](./dynamic/cover.md)
   - [Handout mode](./dynamic/handout.md)
@@ -22,4 +22,11 @@
     - [University](./themes/gallery/university.md)
     - [Bipartite](./themes/gallery/bipartite.md)
   - [Build your own](./themes/your-own.md)
-  - [Helpers for theme authors](./themes/helpers.md)
+- [Utilities](./utils/utils.md)
+  - [Side by side](./utils/side-by-side.md)
+  - [Fit to height](./utils/fit-to-height.md)
+  - [Progress](./utils/progress.md)
+  - [Sections](./utils/sections.md)
+- [External tools](./external/external.md)
+  - [pdfpc](./external/pdfpc.md)
+- [Changelog](./changelog.md)

book/src/changelog.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## v0.3.0
+
+- The previously existing module `helpers` was transformed to `utils` and now
+  contains many more useful features.
+- The modules `logic` and `utils` are now directly accesible when importing
+  Polylux (it was a bug that it did not work previously).
+- We finally have an ergonomic `#pause` function that does not expect the user
+  to keep track of some counter themselves.
+- The `#alternatives` function has gained lots of friends that make specific
+  situations a bit more convenient, namely `#alternatives-match`,
+  `alternatives-cases`, and `alternatives-fn`.
+  Also, there is a parameter `repeat-last` for `#alternatives` now.
+- Bullet lists, enumerations, and term lists now have custom functions to display
+  them dynamically: `#list-one-by-one`, `#enum-one-by-one`, and `#terms-one-by-one`.
+- There is a new function `#fit-to-height` that allows you to resize content to
+  a given height (especially make it fill the remaining space on a slide!)
+  Thank you to [@ntjess](https://github.com/ntjess) for the initial implementation!
+- Previously, certain themes allowed you to easily put multiple content elements
+  next to each other.
+  This is now a commonly available function: `#side-by-side`.
+  You can use it regardless of any theme and the functionality was removed from
+  the previously implementing themes.
+- Polylux now has special support for the pdfpc presentation viewer.
+  You can add speaker notes, hide slides, configure the timer, and more all from
+  within your Typst source file.
+  Thank you to [@JuliusFreudenberger](https://github.com/JuliusFreudenberger)
+  for the inspiration and for creating the `polylux2pdfpc` AUR package.

book/src/diy/diy.md

@@ -83,7 +83,7 @@ As a quick example, let's add a little quiz to our slides:
 
   What is the capital of the Republic of Benin?
 
-  #uncover(2)[Cotonou]
+  #uncover(2)[Porto-Novo]
 ]
 ```
 ![quiz](quiz.png)
@@ -94,7 +94,7 @@ The next sections will explain dynamic content in polylux in all its details.
 For reference, here is the full source code for the slides we developed in this
 section:
 ```typ
-#import "@preview/polylux:0.2.0": *
+{{#include ../IMPORT.typ}}
 
 #set page(paper: "presentation-16-9", fill: teal.lighten(90%))
 #set text(size: 25pt, font: "Blogger Sans")
@@ -118,7 +118,7 @@ section:
 
   What is the capital of the Republic of Benin?
 
-  #uncover(2)[Cotonou]
+  #uncover(2)[Porto-Novo]
 ]
 ```
 

book/src/diy/quiz.typ

@@ -22,5 +22,5 @@
 
   What is the capital of the Republic of Benin?
 
-  #uncover(2)[Cotonou]
+  #uncover(2)[Porto-Novo]
 ]

book/src/dynamic/alternatives-cases.typ

@@ -0,0 +1,22 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 50pt)
+
+/*
+#alternatives-match((
+  "1, 3" : [
+    Some text
+  ],
+  "2" : [
+    #set text(fill: teal)
+    Some text
+  ],
+))
+*/
+
+#polylux-slide[
+#alternatives-cases(("1, 3", "2"), case => [
+  #set text(fill: teal) if case == 1
+  Some text
+])
+]

book/src/dynamic/alternatives-fn.typ

@@ -0,0 +1,9 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 60pt)
+
+#polylux-slide[
+#alternatives-fn(start: 2, count: 7, subslide => {
+  numbering("(i)", subslide)
+})
+]

book/src/dynamic/alternatives-match.typ

@@ -0,0 +1,10 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 50pt)
+
+#polylux-slide[
+#alternatives-match((
+  "1, 3-5": [this text has the majority],
+  "2, 6": [this is shown less often]
+))
+]

book/src/dynamic/alternatives-repeat-last.typ

@@ -0,0 +1,9 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 50pt)
+
+#polylux-slide[
+#alternatives(repeat-last: true)[temporary][transitory][ephemeral][permanent!]
+
+#uncover(5)[Did I miss something?]
+]

book/src/dynamic/alternatives.md

@@ -1,6 +1,5 @@
 # `#alternatives` to substitute content
-The so far discussed helpers `#one-by-one`, `#line-by-line`, and `pause` all
-build upon `#uncover`.
+The so far discussed helpers `#pause`, `#one-by-one` etc. all build upon `#uncover`.
 There is an analogon to `#one-by-one` that is based on `#only`, namely
 `#alternatives`.
 You can use it to show some content on one subslide, then substitute it by
@@ -36,6 +35,19 @@ it uses the same amount of space as `Christopher`.
 In a sense, it is like a mix of `#only` and `#uncover` with some reserving of
 space.
 
+### Repeat last content
+In case you have other dynamic content on a slide that happens after the contents
+of `#alternatives` are exhausted, you might want to not have the `#alternatives`
+element disappear but instead continue to show its last content argument.
+To achieve this, you can use the `repeat-last` parameter:
+```typ
+{{#include alternatives-repeat-last.typ:6:9}}
+```
+resulting in
+
+![alternatives-repeat-last](alternatives-repeat-last.png)
+
+### Positioning
 By default, all elements that enter an `#alternatives` command are aligned at
 the bottom left corner.
 This might not always be the desired or the most pleasant way to position it, so
@@ -49,6 +61,62 @@ makes the mathematical terms look better positioned:
 
 ![alternatives-position](alternatives-position.png)
 
-Similar to `#one-by-one` and `#line-by-line`, `#alternatives` also has an optional
-`start` argument that works just the same as for the other two.
+All functions described on this page have such a `position` argument.
+
+Similar to `#one-by-one`, `#alternatives` also has an optional `start` argument
+that works just the same.
+
+## `#alternatives-match`
+`#alternatives` has a couple of "cousins" that might be more convenient in some
+situations.
+The first one is `#alternatives-match` that has a name inspired by match-statements
+in many functional programming languages.
+The idea is that you give it a dictionary mapping from subslides to content:
+```typ
+{{#include alternatives-match.typ:6:9}}
+```
+resulting in
+
+![alternatives-match](alternatives-match.png)
+
+**Note** that it is your responsibility to make sure that the subslide sets are
+mutually disjoint.
+
+## `#alternatives-cases`
+You can use this function if you want to have one piece of content that changes
+only slightly depending of what "case" of subslides you are in.
+So instead of
+```typ
+{{#include alternatives-cases.typ:6:14}}
+```
+you can avoid duplication and write
+```typ
+{{#include alternatives-cases.typ:18:21}}
+```
+using a function that maps the current "case" to content, resulting in
+
+![alternatives-cases](alternatives-cases.png)
+
+**Note** that the cases are 0-indexed (as are Typst arrays).
+
+
+## `#alternatives-fn`
+Finally, you can have very fine-grained control over the content depending on
+the current subslide by using `#alternatives-fn`.
+It accepts a function (hence the name) that maps the current subslide index to
+some content.
+
+Similar to `#alternatives`, it accepts an optional `start` parameter that has a
+default of `1`.
+`#alternatives-fn` only knows for how long to display something, though, if you
+provide either the number of subslides (`count` parameter) or the last subslide
+index (`end` parameter).
+So exactly one of them is necessary.
+
+For example:
+```typ
+{{#include alternatives-fn.typ:6:8}}
+```
+resulting in
 
+![alternatives-fn](alternatives-fn.png)

book/src/dynamic/cover.md

@@ -1,6 +1,6 @@
 # Cover mode
-Covered content (using `#uncover`, `#one-by-one`, `#line-by-line`, or `pause`)
-is completely invisible, by default.
+Covered content (using `#uncover`, `#one-by-one`, `#line-by-line`, or
+`#{list|enum|terms}-one-by-one`) is completely invisible, by default.
 You can decide to make it visible but less prominent using the optional `mode`
 argument to each of those functions.
 The `mode` argument takes two different values: `"invisible"` (the default) and
@@ -10,7 +10,7 @@ With `mode: "transparent"`, text is printed in a light gray.
 
 Use it as follows:
 ```typ
-{{#include cover.typ:6:16}}
+{{#include cover.typ:6:15}}
 ```
 resulting in
 

book/src/dynamic/cover.typ

@@ -3,7 +3,7 @@
 #set text(size: 30pt)
 
 #polylux-slide[
-#uncover("3-4", mode: "transparent")[abc]
+#uncover(3, mode: "transparent")[abc]
 
 #one-by-one(start: 2, mode: "transparent")[def ][ghi]
 
@@ -12,6 +12,5 @@
   - mno
 ]
 
-#show: pause(4, mode: "transparent")
-pqr
+#enum-one-by-one(mode: "transparent", tight: false)[pqr][stu][vwx]
 ]

book/src/dynamic/enum-one-by-one.typ

@@ -0,0 +1,7 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 50pt)
+
+#polylux-slide[
+#enum-one-by-one(numbering: "i)", number-align: start)[first][second][third]
+]

book/src/dynamic/helper.md

@@ -4,8 +4,8 @@ situations for which helper functions are provided.
 We call them "higher level" because they use `#only` and `#uncover` under the
 hood and operate on larger pieces of content.
 
-For the common case of succesively revealing content, there are `#one-by-one`,
-`#line-by-line`, and `pause`.
-For substituting content, we have `#alternatives`.
+For the common case of succesively revealing content, there are `#pause` and
+`#one-by-one` and its friends.
+For substituting content, we have `#alternatives` in different variants.
 The following sections will describe these functions in detail.
 

book/src/dynamic/list-one-by-one.typ

@@ -0,0 +1,7 @@
+#import "../../../polylux.typ": *
+#set page(paper: "presentation-16-9")
+#set text(size: 50pt)
+
+#polylux-slide[
+#list-one-by-one(marker: [--], tight: false)[first][second][third]
+]