diff options
| -rw-r--r-- | crates/typst-library/src/lib.rs | 2 | ||||
| -rw-r--r-- | docs/reference/groups.yml | 53 | ||||
| -rw-r--r-- | docs/src/lib.rs | 2 |
3 files changed, 55 insertions, 2 deletions
diff --git a/crates/typst-library/src/lib.rs b/crates/typst-library/src/lib.rs index c39024f7..fa797788 100644 --- a/crates/typst-library/src/lib.rs +++ b/crates/typst-library/src/lib.rs @@ -148,7 +148,7 @@ pub struct Library { /// The default style properties (for page size, font selection, and /// everything else configurable via set and show rules). pub styles: Styles, - /// The standard library as a value. Used to provide the `std` variable. + /// The standard library as a value. Used to provide the `std` module. pub std: Binding, /// In-development features that were enabled. pub features: Features, diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index e5aa7e99..c7e3d996 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -137,6 +137,59 @@ In addition to the functions listed below, the `calc` module also defines the constants `pi`, `tau`, `e`, and `inf`. +- name: std + title: Standard library + category: foundations + path: ["std"] + details: | + A module that contains all globally accessible items. + + # Using "shadowed" definitions + The `std` module is useful whenever you overrode a name from the global + scope (this is called _shadowing_). For instance, you might have used the + name `text` for a parameter. To still access the `text` element, write + `std.text`. + + ```example + >>> #set page(margin: (left: 3em)) + #let par = [My special paragraph.] + #let special(text) = { + set std.text(style: "italic") + set std.par.line(numbering: "1") + text + } + + #special(par) + + #lorem(10) + ``` + + # 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 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)). + + This 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 versions. Since the parameters accepted by the `tiling` + function match those of the older `pattern` function, using the `tiling` + function when available and falling back to `pattern` otherwise will unify + the usage across all versions. Note that, when creating a polyfill, + [`sys.version`]($category/foundations/sys) can also be very useful. + + ```typ + #let tiling = if "tiling" in dictionary(std) { + tiling + } else { + pattern + } + + ... + ``` + - name: sys title: System category: foundations diff --git a/docs/src/lib.rs b/docs/src/lib.rs index b81f0dc6..9bd21c2e 100644 --- a/docs/src/lib.rs +++ b/docs/src/lib.rs @@ -37,7 +37,7 @@ static GROUPS: LazyLock<Vec<GroupData>> = LazyLock::new(|| { let mut groups: Vec<GroupData> = yaml::from_str(load!("reference/groups.yml")).unwrap(); for group in &mut groups { - if group.filter.is_empty() { + if group.filter.is_empty() && group.name != "std" { group.filter = group .module() .scope() |