I think this part could be improved. I'm not sure what you mean by "read-only". What would the user expect to be modifiable that is not?

I like the example, though.

I hope the new version is an improvement.

the term "query" has a rather specific connotation in Typst and should be avoided here imo (also a bunch of times more below)

I deliberately usequery when I refer to the specific typst meaning, and plain text to just use the English term. IMHO, there is no confusion. Anyway, what synonym would not collide with anything in your opinion?

I think "retrieve" (as you suggested below) is good. The difference between "query" andquery is a bit too subtle imo.

Saying "This is the purpose of the context keyword" is a bit strong since it's not the only purpose of it

Please enlighten me about other purposes (or give me a pointer).

Context also provides the current location viahere().

You should be proud of how simple it is (in comparison to the competition :-).

:D I'm trying to reduce the use of "simple" in my technical writing as things are differently simple/hard for different people and it's typically unnecessary fluff.

"calling" isn't really the correct term I think, as it's not a function (this also appears various times more below)

I'm running out of words -- "query" is also forbidden :-) How about "retrieving"?

Retrieving is good.

Again: people read documentation selectively. "Important:" is meant to catch their attention. That these fields are not accessible outside of acontext was another big surprise to me -- remember that I even made a feature request because I coudn't deduce this from the documentation. I would rather add the explanation to more places to hammer it into every readers brain.

It stuck out to me because in my opinion it's not clearly more important than the other information in this section.

Regardless of that, I think this section could be expanded to clarify when exactly fields are present on content. Essentially

• fields for required arguments are always accessible
• fields for optional arguments that were provided in the element's constructor are accessible on a constructed element
• fields for optional arguments that weren't mentioned in the constructor are only available when the element is "materialized", this is the case when it's the shown element in a show rule or when the element is returned from a query
• If an element is not materialized, it's fields are not available, also not within acontext expression

Meanwhile, fields onelement functions arenever available without an established context.

What does "static" mean here?

I think something like this would be more correct. Properties are not really immutable: you can still change them, it's just not observable within the same context expression. Maybe my second sentence is redundant with your next paragraph though.

Maybe the following example could even have a nested context expression, but that might be too much.

I would suggest`"en"`, because the output is technically code here.

This sentence feels weird to me. What's "it"?

The next sentence is great though, it makes it really clear that multiple small context blocks can behave very differently compared to a single big one.

Both "content creation instructions" and "content expressions" feel obscure to me

Depending on the target audience, this example might be a bit hard to follow (first, we define a function that won't be used for now, then, opencontext, then, do some stuff, then,show: template, then you need to look at whattemplate does, then...).

I copied this example from the original documentation. I think readers will easily figure out its meaning after the previous explanations. It will be good if it takes a moment of extra thinking, because this will make the rules stick in the brain.

The value oftext.fill.darken(20%) is not content, but the value ofcontext text.fill.darken(20%) is.

I would say it's never really assigned per se. But maybe I'm just nitpicking too much.

While your explanation may be technically more precise, I think it is harder to understand for newcomers. I don't see why "assigned upon entry into the context" is wrong and would rather like to keep it. May "entry into the context block", but I'm not sure of this is better.

Personally, I'd consider getting rid of this example, since it is the first one in the page and we should avoid accidentally encouraging the common mistake of trying to use the value returned incontext directly, e.g. in2 * context text.size or"en" == context text.lang.

It could be improved by adding some logic within the context block.

In fact, we could consider mentioning this issue very early on below, when saying that context returns content, if possible. (Needs further discussion.)

Actually, this is alreadybriefly mentioned at the top, but either way people generally skim the docs for examples they may paste elsewhere (for good reason), so I'd argue this is still a concern, and an explicit (counter-)example would be nice.

This example is the "Hello world" of contexts. Everyone knows that "Hello world" is not very useful, but it gets across a few very basic things (such as how the context keywords looks like, that properties are accessed by field syntax, and that they can be displayed). Of course, a different example (instead oflang) might be more instructive.

BTW, the example is not completely pointless -- it is useful as a quick-and-dirty way of inspecting what the current value of some property is.

A remark about the error message when a field is accessed outside of a context:

#text.lang// => "Can only be used when context is known."

This message is a mystery for beginners -- when you haven't heard about thecontext concept (and associated keyword) and read "context is known" with its generic, everyday-language meaning, you have no idea what to do (and this unfortunately applies to many other error messages as well). Worse, when I first opened the context documentation, I got the feeling that this is meant for advanced users and wouldn't be needed right now. In reality, contexts are absolutely fundamental, and an improved documentation should get this across.

This example is the "Hello world" of contexts. Everyone knows that "Hello world" is not very useful, but it gets across a few very basic things (such as how the context keywords looks like, that properties are accessed by field syntax, and that they can be displayed)

Yeah of course, but as someone who is often active in the typst support channels, i find the problem I mentioned to be rather common across beginners. See alsohttps://forum.typst.app/t/why-is-the-value-i-receive-from-context-always-content/164/

It is possible to keep the example in some way, but maybe it just shouldn't be thefirst.

It's true that it's a very common problem with beginners, but I'm not sure that this specific example is the problem. No matter what you put there, people will think that's the way it works. So I think we can keep that. But I agree that we should have more explanation specific to that problem somewhere relatively early in the docs. Doesn't necessarily have to be part of this PR though.

This mention to property assignment (at least here) is confusing, since that was never suggested to be possible in the first place, and doesn't seem like something that needs to be mentioned anyway as the error should be straightforward. Set rules, OTOH, don't produce errors, so they are definitely tricky and should be the main focus of this paragraph.

This mention to property assignment (at least here) is confusing, since that was never suggested to be possible in the first place

The problem with your argument is that anyone with only the least programming experience assumes by default that properties can be assigned -- it is just how it works in most languages. That typst never suggested the possibility is irrelevant, the brain automatically relates new stuff to what it already knows.

In fact, a major reason why I struggled with the typst documentation (and take the time to propose improvements) is that one has to unlearn various things that other programming languages take for granted. You absolutely must mention and explain when typst deviates from the mainstream.

Yes, I agree this should be mentioned, but my main point is that this isn't related tocontext itself and feels out of place. This is rather related toset rules themselves - that's how you set properties on elements, not through assignment.

In other words, sinceset rules from outside are what define the value oftext.lang in the first place, one could naturally expect that aset rule insidecontext { ... } would also change it within. That is not the case.

As a compromise, the suggestion of not being able to assign totext.lang could be moved to a note after the phrase or paragraph, e.g. "set rules cannot changetext.lang within the context (nor can you assign to them, as only set rules can influence the default values of element properties)."

In other words, since set rules from outside are what define the value of text.lang in the first place, one could naturally expect that a set rule inside context { ... } would also change it within. That is not the case.

Isn't this exactly what my proposed documentation says?

Isn't this exactly what my proposed documentation says?

I'm effectively proposing for that to be theonly thing it says, and mention the assignment thing elsewhere, or as a sidenote.

I agree that thetext.lang = "de" is too front-and-center here. In particular, it also sounds like the fact that assignments are not allowed is related to the constants-ness and set rules can somehow ignore the constantness --- which they don't. I think it would be good to decouple the talk about constantness from the fact that you should use set rules and not assignment.

Maybe a bit more elementary:

I do not find this formulation helpful. Why restrict the statement to set rules applied in show rules?

Otherwise they don't affect context at all. That's the only way they could potentially change a property (and, indeed, they affect nested contexts). But a show rule transforming element A into B wouldn't have any impact whatsoever.

This is mostly due to how theshow syntax is a bit overloaded. Only "everything show rules" - equivalent to passing the rest of a scope to a function - can also apply show rules on the current scope.

I like@PgBiel's proposed addition.

This has the unfortunate pitfall of not being overridable by a later set rule, since an earlier show rule executes last... it's also whyshow: set rules are usually recommended instead.

Of course, that's not a problem if you never try to override it, but wanted to highlight this for discussion.

You mean the example should be written like this?

#showmath.equation.where(block:true):setpar(leading:par.leading*200%)

This is a typical example of a problem I noticed with the current documentation: After reading it, one tends to overcomplicate solutions (and I mean by alot).

BTW, the precedence of the rules would deserve its own documentation section.

You mean the example should be written like this?

#showmath.equation.where(block:true):setpar(leading:par.leading*200%)

Unfortunately, this doesn't work becausepar.leading * 200% is evaluated when the show rule is first processed (without context), not when the equation is visited.

Not sure if this change belongs in this PR, but I'll let@laurmaedje have the final word on this.

Not sure if it is worth moving this to a PR of its own. In any case, this is another place where it is necessary to unlearn experience from other programming languages, and therefore important to mention.

I think it would be good to move this into its own PR.