First attempt at documentation rewording

This commit is contained in:
Ullrich Koethe 2025-03-04 15:12:41 +01:00 committed by GitHub
parent 6271cdceae
commit 3dea9b3914
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -26,37 +26,51 @@ in some places that are also aware of their location in the document:
outline, for instance, also provide the proper context to resolve counters. outline, for instance, also provide the proper context to resolve counters.
## Style context ## Style context
With set rules, we can adjust style properties for parts or the whole of our Style properties often change within a document, for example by applying set
document. We cannot access these without a known context, as they may change rules. Consequently, to retrieve settings one must first specify the context
throughout the course of the document. When context is available, we can where the query is to be executed. Within a given context, the property
retrieve them simply by accessing them as fields on the respective element information is provided by a simple field access syntax. For example,
function. `text.lang` asks for the current language setting. In its simplest form, the
`context` keyword refers to "right here":
```example ```example
#set text(lang: "de") #set text(lang: "de")
#context text.lang #context text.lang
``` ```
As explained above, a context expression is reactive to the different Note that calling `#text.lang` directly would be an error, because the request
environments it is placed into. In the example below, we create a single context cannot be answered without knowledge of the context. The fields supported by
expression, store it in the `value` variable and use it multiple times. Each use a given element function are documented **where??** and can be retrieved in a
properly reacts to the current surroundings. document by calling **what?? (something like `fields()`)**.
When the language setting changes, the responses to the query change accordingly:
_Remark: The old example with `#let value = context text.lang` is very confusing at
this early stage of the explanation and does more harm than good._
```example ```example
#let value = context text.lang #context text.lang
#value
#set text(lang: "de") #set text(lang: "de")
#value #context text.lang
#set text(lang: "fr") #set text(lang: "fr")
#value #context text.lang
``` ```
Crucially, upon creation, `value` becomes opaque [content] that we cannot peek The output of a `#context ...` call is _read-only_ (in the form of `[content]`).
into. It can only be resolved when placed somewhere because only then the Allowing write access would likely result in invalid code, because the context
context is known. The body of a context expression may be evaluated zero, one, might have already changed in the meantime. Therefore, temporary changes of
or multiple times, depending on how many different places it is put into. settings must be done within the context, and they are only active until the
end of the context's scope:
```example
#context {
// the context allows you to retrieve the current text.size
set text(size: text.size * 200%)
[large text]
}
original size
```
## Location context ## Location context
We've already seen that context gives us access to set rule values. But it can We've already seen that context gives us access to set rule values. But it can