diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/context.md | 38 | ||||
| -rw-r--r-- | docs/reference/groups.yml | 12 | ||||
| -rw-r--r-- | docs/reference/scripting.md | 49 | ||||
| -rw-r--r-- | docs/reference/styling.md | 19 | ||||
| -rw-r--r-- | docs/reference/syntax.md | 28 | ||||
| -rw-r--r-- | docs/reference/welcome.md | 8 |
6 files changed, 74 insertions, 80 deletions
diff --git a/docs/reference/context.md b/docs/reference/context.md index 5ebcfbe7..8c6ee9de 100644 --- a/docs/reference/context.md +++ b/docs/reference/context.md @@ -53,11 +53,10 @@ properly reacts to the current surroundings. #value ``` -Crucially, upon creation, `value` becomes opaque [content]($content) that we -cannot peek into. It can only be resolved when placed somewhere because only -then the context is known. The body of a context expression may be evaluated -zero, one, or multiple times, depending on how many different places it is put -into. +Crucially, upon creation, `value` becomes opaque [content] that we cannot peek +into. It can only be resolved when placed somewhere because only then the +context is known. The body of a context expression may be evaluated zero, one, +or multiple times, depending on how many different places it is put into. ## Location context Context can not only give us access to set rule values. It can also let us know @@ -89,20 +88,19 @@ resolved numbers. Thus, we get the following result: #context counter(heading).get() ``` -For more flexibility, we can also use the [`here`]($here) function to directly -extract the current [location]($location) from the context. The example below +For more flexibility, we can also use the [`here`] function to directly extract +the current [location] from the context. The example below demonstrates this: - We first have `{counter(heading).get()}`, which resolves to `{(2,)}` as before. -- We then use the more powerful [`counter.at`]($counter.at) with - [`here`]($here), which in combination is equivalent to `get`, and thus get - `{(2,)}`. -- Finally, we use `at` with a [label]($label) to retrieve the value of the - counter at a _different_ location in the document, in our case that of the - introduction heading. This yields `{(1,)}`. Typst's context system gives us - time travel abilities and lets us retrieve the values of any counters and - states at _any_ location in the document. +- We then use the more powerful [`counter.at`] with [`here`], which in + combination is equivalent to `get`, and thus get `{(2,)}`. +- Finally, we use `at` with a [label] to retrieve the value of the counter at a + _different_ location in the document, in our case that of the introduction + heading. This yields `{(1,)}`. Typst's context system gives us time travel + abilities and lets us retrieve the values of any counters and states at _any_ + location in the document. ```example #set heading(numbering: "1.") @@ -121,10 +119,10 @@ demonstrates this: ``` As mentioned before, we can also use context to get the physical position of -elements on the pages. We do this with the [`locate`]($locate) function, which -works similarly to `counter.at`: It takes a location or other -[selector]($selector) that resolves to a unique element (could also be a label) -and returns the position on the pages for that element. +elements on the pages. We do this with the [`locate`] function, which works +similarly to `counter.at`: It takes a location or other [selector] that resolves +to a unique element (could also be a label) and returns the position on the +pages for that element. ```example Background is at: \ @@ -139,7 +137,7 @@ Background is at: \ ``` There are other functions that make use of the location context, most -prominently [`query`]($query). Take a look at the +prominently [`query`]. Take a look at the [introspection]($category/introspection) category for more details on those. ## Nested contexts diff --git a/docs/reference/groups.yml b/docs/reference/groups.yml index 16ded697..0cbf656a 100644 --- a/docs/reference/groups.yml +++ b/docs/reference/groups.yml @@ -9,8 +9,8 @@ details: | Alternate typefaces within formulas. - These functions are distinct from the [`text`]($text) function because math - fonts contain multiple variants of each letter. + These functions are distinct from the [`text`] function because math fonts + contain multiple variants of each letter. - name: styles title: Styles @@ -20,8 +20,8 @@ details: | Alternate letterforms within formulas. - These functions are distinct from the [`text`]($text) function because math - fonts contain multiple variants of each letter. + These functions are distinct from the [`text`] function because math fonts + contain multiple variants of each letter. - name: sizes title: Sizes @@ -131,10 +131,10 @@ This module defines the following items: - - The `sys.version` constant (of type [`version`]($version)) that specifies + - The `sys.version` constant (of type [`version`]) that specifies the currently active Typst compiler version. - - The `sys.inputs` [dictionary]($dictionary), which makes external inputs + - The `sys.inputs` [dictionary], which makes external inputs available to the project. An input specified in the command line as `--input key=value` becomes available under `sys.inputs.key` as `{"value"}`. To include spaces in the value, it may be enclosed with diff --git a/docs/reference/scripting.md b/docs/reference/scripting.md index b66b9896..8cfb9698 100644 --- a/docs/reference/scripting.md +++ b/docs/reference/scripting.md @@ -46,9 +46,9 @@ _blocks:_ With content blocks, you can handle markup/content as a programmatic value, store it in variables and pass it to [functions]($function). Content blocks are delimited by square brackets and can contain arbitrary markup. A - content block results in a value of type [content]($content). An - arbitrary number of content blocks can be passed as trailing arguments to - functions. That is, `{list([A], [B])}` is equivalent to `{list[A][B]}`. + content block results in a value of type [content]. An arbitrary number of + content blocks can be passed as trailing arguments to functions. That is, + `{list([A], [B])}` is equivalent to `{list[A][B]}`. Content and code blocks can be nested arbitrarily. In the example below, `{[hello ]}` is joined with the output of `{a + [ the ] + b}` yielding @@ -189,14 +189,14 @@ together into one larger array. For loops can iterate over a variety of collections: - `{for value in array {..}}` \ - Iterates over the items in the [array]($array). The destructuring syntax - described in [Let binding]($scripting/#bindings) can also be used here. + Iterates over the items in the [array]. The destructuring syntax described in + [Let binding]($scripting/#bindings) can also be used here. - `{for pair in dict {..}}` \ - Iterates over the key-value pairs of the [dictionary]($dictionary). - The pairs can also be destructured by using `{for (key, value) in dict {..}}`. - It is more efficient than `{for pair in dict.pairs() {..}}` because it doesn't - create a temporary array of all key-value pairs. + Iterates over the key-value pairs of the [dictionary]. The pairs can also be + destructured by using `{for (key, value) in dict {..}}`. It is more efficient + than `{for pair in dict.pairs() {..}}` because it doesn't create a temporary + array of all key-value pairs. - `{for letter in "abc" {..}}` \ Iterates over the characters of the [string]($str). Technically, it iterates @@ -205,9 +205,9 @@ For loops can iterate over a variety of collections: codepoints, like a flag emoji. - `{for byte in bytes("😀") {..}}` \ - Iterates over the [bytes]($bytes), which can be converted from a [string]($str) - or [read]($read) from a file without encoding. Each byte value is an - [integer]($int) between `{0}` and `{255}`. + Iterates over the [bytes], which can be converted from a [string]($str) or + [read] from a file without encoding. Each byte value is an [integer]($int) + between `{0}` and `{255}`. To control the execution of the loop, Typst provides the `{break}` and `{continue}` statements. The former performs an early exit from the loop while @@ -233,10 +233,10 @@ The body of a loop can be a code or content block: ## Fields You can use _dot notation_ to access fields on a value. The value in question can be either: -- a [dictionary]($dictionary) that has the specified key, -- a [symbol]($symbol) that has the specified modifier, -- a [module]($module) containing the specified definition, -- [content]($content) consisting of an element that has the specified field. The +- a [dictionary] that has the specified key, +- a [symbol] that has the specified modifier, +- a [module] containing the specified definition, +- [content] consisting of an element that has the specified field. The available fields match the arguments of the [element function]($function/#element-functions) that were given when the element was constructed. @@ -253,8 +253,8 @@ can be either: ## Methods A _method call_ is a convenient way to call a function that is scoped to a -value's [type]($type). For example, we can call the [`str.len`]($str.len) -function in the following two equivalent ways: +value's [type]. For example, we can call the [`str.len`]($str.len) function in +the following two equivalent ways: ```example #str.len("abc") is the same as @@ -291,14 +291,12 @@ module can refer to the content and definitions of another module in multiple ways: - **Including:** `{include "bar.typ"}` \ - Evaluates the file at the path `bar.typ` and returns the resulting - [content]($content). + Evaluates the file at the path `bar.typ` and returns the resulting [content]. - **Import:** `{import "bar.typ"}` \ - Evaluates the file at the path `bar.typ` and inserts the resulting - [module]($module) into the current scope as `bar` (filename without - extension). You can use the `as` keyword to rename the imported module: - `{import "bar.typ" as baz}` + Evaluates the file at the path `bar.typ` and inserts the resulting [module] + into the current scope as `bar` (filename without extension). You can use the + `as` keyword to rename the imported module: `{import "bar.typ" as baz}` - **Import items:** `{import "bar.typ": a, b}` \ Evaluates the file at the path `bar.typ`, extracts the values of the variables @@ -327,8 +325,7 @@ and a version. ``` The `preview` namespace contains packages shared by the community. You can find -a searchable list of available community packages in the [packages]($packages) -section. +a searchable list of available community packages in the [packages] section. If you are using Typst locally, you can also create your own system-local packages. For more details on this, see the diff --git a/docs/reference/styling.md b/docs/reference/styling.md index 1c3fd173..b0b7ab71 100644 --- a/docs/reference/styling.md +++ b/docs/reference/styling.md @@ -62,11 +62,10 @@ a _set-if_ rule. ## 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 [selector]($selector), a colon and then a set -rule. The most basic form of selector is an -[element function]($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. +`{show}` keyword followed by a [selector], a colon and then a set rule. The most +basic form of selector is an [element function]($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) @@ -79,11 +78,11 @@ With show-set rules you can mix and match properties from different functions to 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 after the colon with an arbitrary [function]($function). -This function receives the element in question and can return arbitrary content. -The available [fields]($scripting/#fields) on the element passed to the function -again match the parameters of the respective element function. Below, we define -a show rule that formats headings for a fantasy encyclopedia. +replace the set rule after the colon with an arbitrary [function]. This function +receives the element in question and can return arbitrary content. The available +[fields]($scripting/#fields) on the element passed to the function again match +the parameters of the respective element function. Below, we define a show rule +that formats headings for a fantasy encyclopedia. ```example #set heading(numbering: "(I)") diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md index 40213fe9..2cdccc59 100644 --- a/docs/reference/syntax.md +++ b/docs/reference/syntax.md @@ -36,20 +36,20 @@ more about their syntax and usage. | Name | Example | See | | ------------------ | ------------------------ | ---------------------------- | -| Paragraph break | Blank line | [`parbreak`]($parbreak) | -| Strong emphasis | `[*strong*]` | [`strong`]($strong) | -| Emphasis | `[_emphasis_]` | [`emph`]($emph) | -| Raw text | ``[`print(1)`]`` | [`raw`]($raw) | -| Link | `[https://typst.app/]` | [`link`]($link) | -| Label | `[<intro>]` | [`label`]($label) | -| Reference | `[@intro]` | [`ref`]($ref) | -| Heading | `[= Heading]` | [`heading`]($heading) | -| Bullet list | `[- item]` | [`list`]($list) | -| Numbered list | `[+ item]` | [`enum`]($enum) | -| Term list | `[/ Term: description]` | [`terms`]($terms) | +| Paragraph break | Blank line | [`parbreak`] | +| Strong emphasis | `[*strong*]` | [`strong`] | +| Emphasis | `[_emphasis_]` | [`emph`] | +| Raw text | ``[`print(1)`]`` | [`raw`] | +| Link | `[https://typst.app/]` | [`link`] | +| Label | `[<intro>]` | [`label`] | +| Reference | `[@intro]` | [`ref`] | +| Heading | `[= Heading]` | [`heading`] | +| Bullet list | `[- item]` | [`list`] | +| Numbered list | `[+ item]` | [`enum`] | +| Term list | `[/ Term: description]` | [`terms`] | | Math | `[$x^2$]` | [Math]($category/math) | -| Line break | `[\]` | [`linebreak`]($linebreak) | -| Smart quote | `['single' or "double"]` | [`smartquote`]($smartquote) | +| Line break | `[\]` | [`linebreak`] | +| Smart quote | `['single' or "double"]` | [`smartquote`] | | Symbol shorthand | `[~, ---]` | [Symbols]($category/symbols/sym) | | Code expression | `[#rect(width: 1cm)]` | [Scripting]($scripting/#expressions) | | Character escape | `[Tweet at us \#ad]` | [Below](#escapes) | @@ -70,7 +70,7 @@ follows: | Bottom attachment | `[$x_1$]` | [`attach`]($category/math/attach) | | Top attachment | `[$x^2$]` | [`attach`]($category/math/attach) | | Fraction | `[$1 + (a+b)/5$]` | [`frac`]($math.frac) | -| Line break | `[$x \ y$]` | [`linebreak`]($linebreak) | +| Line break | `[$x \ y$]` | [`linebreak`] | | Alignment point | `[$x &= 2 \ &= 3$]` | [Math]($category/math) | | Variable access | `[$#x$, $pi$]` | [Math]($category/math) | | Field access | `[$arrow.r.long$]` | [Scripting]($scripting/#fields) | diff --git a/docs/reference/welcome.md b/docs/reference/welcome.md index d312ba07..1154cc52 100644 --- a/docs/reference/welcome.md +++ b/docs/reference/welcome.md @@ -5,10 +5,10 @@ description: | --- # Reference -This reference documentation is a comprehensive guide to all of Typst's -syntax, concepts, types, and functions. If you are completely new to Typst, we -recommend starting with the [tutorial]($tutorial) and then coming back to -the reference to learn more about Typst's features as you need them. +This reference documentation is a comprehensive guide to all of Typst's syntax, +concepts, types, and functions. If you are completely new to Typst, we recommend +starting with the [tutorial] and then coming back to the reference to learn more +about Typst's features as you need them. ## Language The reference starts with a language part that gives an overview over |