Document Order of Show Rule Application
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 56.1k
- Forks
- 1.7k
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 22
Description
Description
The current documentation on show rules does not specify the order in which show rules are applied when multiple affect the same content.
Examples
The following example illustrates a case which I found surprising.
#{
show emph: it => [first #it]
show emph: it => [second #it]
show emph: it => [third #it]
emph("body")
// Produces: third second first _body_
// It seems like the outermost rule was evaluated first here.
}
#{
show emph: it => [first #it]
show emph: it => [second #it.body]
show emph: it => [third #it]
emph("body")
// Produces: third second _body_
// It seems like the second rule was evaluated before the first here.
}
On further investigation, I noticed that each show rule receives the same (original) content, but occurrences of that content are replaced by content produced by another show rule:
#{
[A test: \ ]
show emph: it => {
raw("first: " + repr(it))
linebreak()
it
}
show emph: it => {
raw("second: " + repr(it))
linebreak()
it
}
show emph: it => {
raw("third: " + repr(it))
linebreak()
it
}
emph("body")
}
Produces:
Pseudocode
Inferring from the example, the evaluation might follow a pseudocode like this:
- The original content is remembered.
- The current rule is the outermost rule.
- The current content is the original content.
- Repeat:
- The current rule is evaluated.
- All occurrences of the original content in the current content are replaced with the output.
- If the current content no longer contains the original content or there is no next rule, break the loop.
- Otherwise the new current rule is the next rule.
- The final content is the current content.
I'm not entirely sure that I understand it properly though.
Other Cases To Be Documented
Related to this issue are also special cases such as:
show: setis not semantically identical toshow: it => { set ...; it }(see https://github.com/typst/typst/issues/4591#issuecomment-2242456352)- A potential special case for prioritizing more specific selectors, suggested in #5331
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked show-rules documentation and reproduce the provided Typst examples to establish the current behavior. Document the order of rule application and explain the listed special cases, including set rules and selector specificity, so the examples and semantics are covered.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100