diff options
Diffstat (limited to 'docs/src')
| -rw-r--r-- | docs/src/lib.rs | 4 | ||||
| -rw-r--r-- | docs/src/reference/scripting.md | 38 | ||||
| -rw-r--r-- | docs/src/reference/styling.md | 20 | ||||
| -rw-r--r-- | docs/src/reference/types.md | 64 |
4 files changed, 85 insertions, 41 deletions
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) +``` |