caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-05-14 04:56:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

incorporazed suggestiond by @laurmaedje

Browse Source
This commit is contained in:
Ullrich Koethe 2025-03-25 00:05:09 +01:00 committed by GitHub
parent 26cb2446ff
commit 2dcd988451
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 29 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/reference/language/context.md
View File

@ -25,10 +25,10 @@ in some places that are also aware of their location in the document:
[Show rules]($styling/#show-rules) provide context[^1] and numberings in the [Show rules]($styling/#show-rules) provide context[^1] and numberings in the
outline, for instance, also provide the proper context to resolve counters. outline, for instance, also provide the proper context to resolve counters.
## Behavior of the context keyword ## The context keyword
Style properties frequently change within a document, for example by applying set Style properties frequently change within a document, for example through set
rules. To retrieve such properties in a consistent way, one must first specify rules. To retrieve such properties in a consistent way, one must first specify
the precise context where the property should be retrieved. This can be achieved the precise context where the property should be retrieved. This is achieved
with the `context` keyword. Once the context has been fixed, the property with the `context` keyword. Once the context has been fixed, the property
information is available through standard field access syntax. For example, information is available through standard field access syntax. For example,
`text.lang` asks for the current language setting. In its simplest form, the `text.lang` asks for the current language setting. In its simplest form, the
@ -36,26 +36,27 @@ information is available through standard field access syntax. For example,
```example ```example
#set text(lang: "de") #set text(lang: "de")
// read the language setting "here" // Read the language setting "here".
#context text.lang #context text.lang
``` ```
Note that any attempt to access `#text.lang` directly, i.e. outside of a context, Note that any attempt to access `#text.lang` directly, i.e. outside of a context,
will cause the compiler to issue an error message. The field names supported will cause the compiler to issue an error message, since it cannot determine the
precise location the query refers to. The field names supported
by a given element function always correspond to the named parameters documented by a given element function always correspond to the named parameters documented
on each element's page. on each element's page.
Moreover, some functions, such as [`to-absolute`]($length.to-absolute) Moreover, some functions, such as [`to-absolute`]($length.to-absolute)
and [`counter.display`]($counter.display), are only applicable in a context, and [`counter.display`]($counter.display), are only applicable in a context,
because their results depend on the current settings of style properties. because their results depend on the current settings of style properties.
When another function `foo()` calls a context-dependent function, it becomes When another function `{foo()}` calls a context-dependent function, it becomes
itself context-dependent: itself context-dependent:
```example ```example
#let foo() = 1em.to-absolute() #let foo() = 1em.to-absolute()
#context { #context {
// foo() cannot be called // foo() cannot be called
// outside of a context // outside of a context.
foo() == text.size foo() == text.size
} }
``` ```
@ -71,13 +72,13 @@ changes accordingly:
#context text.lang #context text.lang
``` ```
As you see, the result of a `#context ...` expression can As you see, the result of a `[#context ..]` expression can
be inserted into the document as `content`. Context blocks can be inserted into the document as [content]. Context blocks can
contain arbitrary code beyond the field access. However, contain arbitrary code beyond the field access. However,
and this is often surprisingly for newcomers, context-dependent and this is often surprising for newcomers, context-dependent
property fields remain _constant_ throughout the context's scope. property fields remain _constant_ throughout the context's scope.
This has two important consequences: First, direct property This has two important consequences: First, direct property
assignments like `text.lang = "de"` are _not_ allowed – assignments like `{text.lang = "de"}` are _not_ allowed –
use `set` or `show` rules for this purpose. Second, changes to a use `set` or `show` rules for this purpose. Second, changes to a
property value within a context (e.g. by a `set` rule) are not property value within a context (e.g. by a `set` rule) are not
observable by field access within that same context: observable by field access within that same context:
@ -92,10 +93,10 @@ observable by field access within that same context:
] ]
``` ```
Both reads have the same output `"en"`, because `text.lang` is assigned Both reads have the same output `{"en"}`, because `text.lang` is fixed
upon entry in the context and remains constant until the end of its scope upon entry in the context and remains constant until the end of its scope
(the closing `]`). Thus, the `text.lang` field is not affected by (the closing `]`). Thus, the `text.lang` field is not affected by
#set text(lang: "fr")`, although Read 2 occurs afterwards. Compare `[#set text(lang: "fr")]`, although Read 2 occurs after it. Compare
this to the previous example: There we got two different results because this to the previous example: There we got two different results because
we created two different contexts. we created two different contexts.
@ -113,7 +114,7 @@ usual manner, e.g. by set rules. Consider the same example with font size:
] ]
``` ```
Read 2 still outputs `40pt`, because `text.size` is a constant. Read 2 still outputs `{40pt}`, because `text.size` is a constant.
However, this output is printed in 25pt font, as specified by the set However, this output is printed in 25pt font, as specified by the set
rule before the read. This illustrates the importance of picking the rule before the read. This illustrates the importance of picking the
right insertion point for a context to get access to precisely the right right insertion point for a context to get access to precisely the right
@ -131,8 +132,8 @@ you can use _nested contexts_:
``` ```
All of the above applies to `show` rules analogously. To demonstrate this, All of the above applies to `show` rules analogously. To demonstrate this,
we define a function `template` which is activated by an "everything" show we define a function `{template}` (emulating what a document template
rule in a context: might do) which is activated by an "everything" show rule in a context:
```example ```example
#let template(body) = { #let template(body) = {
@ -154,16 +155,16 @@ context (since `text.size` remains constant there), but Read 3 is
located in a nested context and reflects the new font size set by located in a nested context and reflects the new font size set by
the `show` rule via the `template` function. the `show` rule via the `template` function.
## Using context-dependent property fields to control content appearance ## Setting derived properties in a context
An important purpose of reading the current value of properties is, An important purpose of reading the current value of properties is
of course, to use this information in the calculation of derived to use this information in the calculation of derived properties,
properties, instead of setting those properties manually. For example, instead of setting those properties manually. For example,
you can double the font size like this: you can double the font size like this:
```example ```example
#context [ #context [
// the context allows you to // The context allows you to
// retrieve the current text.size // retrieve the current `text.size`.
#set text(size: text.size * 200%) #set text(size: text.size * 200%)
Large text \ Large text \
] ]
@ -172,7 +173,9 @@ Original size
Since set rules are only active until the end of the enclosing scope, Since set rules are only active until the end of the enclosing scope,
"Original size" is printed with the original font size. "Original size" is printed with the original font size.
For the specific case of accessing `text.size`, context is usually not necessary as the `1em` unit is always equal to the current font size, so the above example is equivalent to For the specific case of accessing `text.size`, context is usually
not necessary as the `{1em}` unit is always equal to the current font
size, so the above example is equivalent to
```example ```example
#[ #[
@ -189,7 +192,7 @@ between the lines of a specific equation block (or any other content):
```example ```example
#let spaced(spacing: 100%, body) = context { #let spaced(spacing: 100%, body) = context {
// access current par.leading in a context // Access current par.leading in a context.
set par(leading: par.leading * spacing) set par(leading: par.leading * spacing)
body body
} }
@ -211,8 +214,8 @@ Normal spacing:
$ x \ x $ $ x \ x $
#show math.equation.where(block: true): it => { #show math.equation.where(block: true): it => {
// access current par.leading in a context, // Access current par.leading in a context,
// established automatically by the show rule // established automatically by the show rule.
set par(leading: par.leading * 200%) set par(leading: par.leading * 200%)
it it
} }