Touch up docs

5 files changed, 90 insertions, 46 deletions

diff --git a/docs/Cargo.toml b/docs/Cargo.toml
index 77d0b375..e2f06e04 100644
--- a/docs/Cargo.toml
+++ b/docs/Cargo.toml
@@ -12,14 +12,14 @@ bench = false
 [dependencies]
 typst = { path = ".." }
 typst-library = { path = "../library" }
-unscanny = "0.1"
+comemo = "0.2.2"
+heck = "0.4"
 include_dir = "0.7"
+once_cell = "1"
 pulldown-cmark = "0.9"
-comemo = "0.2.2"
 serde = { version = "1", features = ["derive"] }
 serde_yaml = "0.8"
-heck = "0.4"
-yaml-front-matter = "0.1"
 unicode_names2 = "0.6.0"
-once_cell = "1"
+unscanny = "0.1"
 ureq = { version = "2.6", features = ["json"] }
+yaml-front-matter = "0.1"
diff --git a/docs/src/lib.rs b/docs/src/lib.rs
index 7333090d..bc445624 100644
--- a/docs/src/lib.rs
+++ b/docs/src/lib.rs
@@ -300,7 +300,7 @@ pub struct FuncModel {
     pub name: &'static str,
     pub display: &'static str,
     pub oneliner: &'static str,
-    pub showable: bool,
+    pub element: bool,
     pub details: Html,
     pub params: Vec<ParamModel>,
     pub returns: Vec<&'static str>,
@@ -340,7 +340,7 @@ fn func_model(resolver: &dyn Resolver, func: &Func, info: &FuncInfo) -> FuncMode
         name: info.name,
         display: info.display,
         oneliner: oneliner(docs),
-        showable: func.element().is_some(),
+        element: func.element().is_some(),
         details: Html::markdown(resolver, docs),
         params: info.params.iter().map(|param| param_model(resolver, param)).collect(),
         returns: info.returns.clone(),
diff --git a/docs/src/reference/scripting.md b/docs/src/reference/scripting.md
index d125bf5b..6af17cc7 100644
--- a/docs/src/reference/scripting.md
+++ b/docs/src/reference/scripting.md
@@ -64,7 +64,7 @@ Content and code blocks can be nested arbitrarily. In the example below,
 }
 ```
 
-## Let bindings { #bindings }
+## Bindings and Destructuring { #bindings }
 As already demonstrated above, variables can be defined with `{let}` bindings.
 The variable is assigned the value of the expression that follows the `=` sign.
 The assignment of a value is optional, if no value is assigned, the variable
@@ -82,7 +82,10 @@ Sum is #add(2, 3).
 ```
 
 Let bindings can also be used to destructure [arrays]($type/array) and
-[dictionaries]($type/dictionary).
+[dictionaries]($type/dictionary). In this case, the left-hand side of the
+assignment should mirror an array or dictionary. The `..` operator can be used
+once in the pattern to collect the remainder of the array's or dictionary's
+items.
 
 ```example
 #let (x, y) = (1, 2)
@@ -117,6 +120,28 @@ You can use the underscore to discard elements in a destructuring pattern:
 The y coordinate is #y.
 ```
 
+Destructuring also work in argument lists of functions ...
+
+```example
+#let left = (2, 4, 5)
+#let right = (3, 2, 6)
+#left.zip(right).map(
+  ((a,b)) => a + b
+)
+```
+
+... and on the left-hand side of normal assignments. This can be useful to
+swap variables among other things.
+
+```example
+#{
+  let a = 1
+  let b = 2
+  (a, b) = (b, a)
+  [a = #a, b = #b]
+}
+```
+
 ## Conditionals { #conditionals }
 With a conditional, you can display or compute different things depending on
 whether some condition is fulfilled. Typst supports `{if}`, `{else if}` and
@@ -206,12 +231,19 @@ can be either:
 - a [dictionary]($type/dictionary) that has the specified key,
 - a [symbol]($type/symbol) that has the specified modifier,
 - a [module]($type/module) containing the specified definition,
-- [content]($type/content) that has the specified field.
+- [content]($type/content) consisting of an element that has the specified
+  field. The available fields match the arguments of the
+  [element function]($type/function/#element-functions) that were given when
+  the element was constructed.
 
 ```example
 #let dict = (greet: "Hello")
 #dict.greet \
 #emoji.face
+
+#let it = [= Heading]
+#it.body \
+#it.level
 ```
 
 ## Methods { #methods }
diff --git a/docs/src/reference/styling.md b/docs/src/reference/styling.md
index a3cc3c2e..d088d61d 100644
--- a/docs/src/reference/styling.md
+++ b/docs/src/reference/styling.md
@@ -12,11 +12,12 @@ of elements.
 
 ## Set rules { #set-rules }
 With set rules, you can customize the appearance of elements. They are written
-as a [function call]($type/function) to the respective function preceded by the
-`{set}` keyword (or `[#set]` in markup). Only optional parameters of that
-function can be provided to the set rule. Refer to each function's documentation
-to see which parameters are optional. In the example below, we use two set rules
-to change the [font family]($func/text.family) and
+as a [function call]($type/function) to an
+[element function]($type/function/#element-functions) preceded by the `{set}`
+keyword (or `[#set]` in markup). Only optional parameters of that function can
+be provided to the set rule. Refer to each function's documentation to see which
+parameters are optional. In the example below, we use two set rules to change
+the [font family]($func/text.family) and
 [heading numbering]($func/heading.numbering).
 
 ```example
@@ -62,9 +63,10 @@ a _set-if_ rule.
 ## Show rules { #show-rules }
 With show rules, you can deeply customize the look of a type of element. The
 most basic form of show rule is a _show-set rule._ Such a rule is written as the
-`{show}` keyword followed by a function name, a colon and then a set rule. This
-lets the set rule only apply to the selected element. In the example below,
-headings become dark blue while all other text stays black.
+`{show}` keyword followed by a [selector]($type/selector), a colon and then a set rule. The most basic form of selector is an
+[element function]($type/function/#element-functions). This lets the set rule
+only apply to the selected element. In the example below, headings become dark
+blue while all other text stays black.
 
 ```example
 #show heading: set text(navy)
@@ -78,7 +80,7 @@ achieve many different effects. But they still limit you to what is predefined
 in Typst. For maximum flexibility, you can instead write a show rule that
 defines how to format an element from scratch. To write such a show rule,
 replace the set rule behind the colon with an arbitrary
-[function]($type/function). This functions receives the element in question and
+[function]($type/function). This function receives the element in question and
 can return arbitrary content. Different
 [fields]($scripting/#fields) are available on the element passed
 to the function. Below, we define a show rule that formats headings for a
diff --git a/docs/src/reference/types.md b/docs/src/reference/types.md
index 1bae6b75..0714d1f7 100644
--- a/docs/src/reference/types.md
+++ b/docs/src/reference/types.md
@@ -644,14 +644,14 @@ Folds all items into a single value using an accumulator function.
 Sums all items (works for any types that can be added).
 
 - default: any (named)
-  If set and the array is empty, sum will return this.
+  What to return if the array is empty. Must be set if the array can be empty.
 - returns: any
 
 ### product()
 Calculates the product all items (works for any types that can be multiplied)
 
 - default: any (named)
-  If set and the array is empty, sum will return this.
+  What to return if the array is empty. Must be set if the array can be empty.
 - returns: any
 
 ### any()
@@ -814,6 +814,13 @@ documentation about [set]($styling/#set-rules) and
 [show]($styling/#show-rules) rules to learn about additional ways
 you can work with functions in Typst.
 
+### Element functions { #element-functions }
+Some functions are associated with _elements_ like [headings]($func/heading) or
+[tables]($func/table). When called, these create an element of their respective
+kind. In contrast to normal functions, they can further be used in
+[set rules]($styling/#set-rules), [show rules]($styling/#show-rules), and
+[selectors]($type/selector).
+
 ### Defining functions { #definitions }
 You can define your own function with a
 [let binding]($scripting/#bindings) that has a parameter list after
@@ -916,30 +923,11 @@ Returns the captured named arguments as a dictionary.
 
 - returns: dictionary
 
-# Module
-An evaluated module, either built-in or resulting from a file.
-
-You can access definitions from the module using
-[field access notation]($scripting/#fields) and interact with it using the
-[import and include syntaxes]($scripting/#modules).
-
-## Example
-```example
-<<< #import "utils.typ"
-<<< #utils.add(2, 5)
-
-<<< #import utils: sub
-<<< #sub(1, 4)
->>> #7
->>>
->>> #(-3)
-```
-
 # Selector
 A filter for selecting elements within the document.
 
 You can construct a selector in the following ways:
-- you can use an element function
+- you can use an element [function]($type/function)
 - you can filter for an element function with
   [specific fields]($type/function.where)
 - you can use a [string]($type/string) or [regular expression]($func/regex)
@@ -948,13 +936,16 @@ You can construct a selector in the following ways:
 - call the [`selector`]($func/selector) function to convert any of the above
   types into a selector value and use the methods below to refine it
 
-A selector is what you can use to query the document for certain types
-of elements. It can also be used to apply styling rules to element. You can
-combine multiple selectors using the methods shown below.
+Selectors are used to [apply styling rules]($styling/#show-rules) to elements.
+You can also use selectors to [query]($func/query) the document for certain
+types of elements.
 
-Selectors can also be passed to several of Typst's built-in functions to
+Furthermore, you can pass a selector to several of Typst's built-in functions to
 configure their behaviour. One such example is the [outline]($func/outline)
-where it can be use to change which elements are listed within the outline.
+where it can be used to change which elements are listed within the outline.
+
+Multiple selectors can be combined using the methods shown below. However, not
+all kinds of selectors are supported in all places, at the moment.
 
 ## Example
 ```example
@@ -1004,3 +995,22 @@ first match of the selector argument.
 - inclusive: boolean (named)
   Whether `start` itself should match or not. This is only relevant if both
   selectors match the same type of element. Defaults to `{true}`.
+
+# Module
+An evaluated module, either built-in or resulting from a file.
+
+You can access definitions from the module using
+[field access notation]($scripting/#fields) and interact with it using the
+[import and include syntaxes]($scripting/#modules).
+
+## Example
+```example
+<<< #import "utils.typ"
+<<< #utils.add(2, 5)
+
+<<< #import utils: sub
+<<< #sub(1, 4)
+>>> #7
+>>>
+>>> #(-3)
+```