typst / typst/typst

Document Order of Show Rule Application

Open
#7,485 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs styling
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:
Image

Pseudocode

Inferring from the example, the evaluation might follow a pseudocode like this:

  1. The original content is remembered.
  2. The current rule is the outermost rule.
  3. The current content is the original content.
  4. Repeat:
    1. The current rule is evaluated.
    2. All occurrences of the original content in the current content are replaced with the output.
    3. If the current content no longer contains the original content or there is no next rule, break the loop.
    4. Otherwise the new current rule is the next rule.
  5. 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:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.