diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index 52b864f33..661877321 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -160,25 +160,26 @@ # Conditional access You can also use this in combination with the [dictionary constructor]($dictionary) to conditionally access global definitions. This - can, for instance, be useful to use new or experimental functionality (like - the [`target`] function) when it is available, while falling back to an - alternative implementation if used on an older Typst version. + can, for instance, be useful to use new or experimental functionality when + it is available, while falling back to an alternative implementation if + used on an older Typst version. In particular, this allows us to create + [polyfills](https://en.wikipedia.org/wiki/Polyfill_(programming)). It can + be as simple as creating an alias to prevent warning messages, for example, + conditionally using `pattern` in Typst version 0.12, but using `tiling` in + newer ones. Since function's [API](https://en.wikipedia.org/wiki/API) + hasn't changed, simply using the `tiling` name to refer to both will unify + function's usage for old and new versions. ```example - #let target = dictionary(std).at( - "target", - default: () => "paged", - ) + #let tiling = dictionary(std).at("tiling", default: none) + #if tiling == none { tiling = pattern } - #context if target() == "html" [ - HTML - ] else [ - Paged - ] + ... ``` - Make sure to use this functionality responsibly as the behavior of your code - can change with new Typst versions! + Note that creating a polyfill means that you are responsible for checking + that it works on older Typst versions (that support `std`). That is, if it + is intended for public use. - name: sys title: System