typst / typst/typst

Introduce `self` in `$scripting/#methods`

Open
#7,532 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs
Dominant language
Rust
Stars
56.1k
Forks
1.7k
Avg merge
3d 10h
Merged PRs (30d)
22

Description

Description

I suggest we introduce the self explicitly in $scripting/#methods.
Specifically, explain how to interpret self appeared in reference pages, like this one:
Image

The error message can be improved as well, but I don't know if that's possible.

Case 1: outline.entry.indented

#show outline.entry: it => {
  outline.entry.indented(
    prefix: it.prefix(),
    inner: it.body(),
    gap: 12em,
  )
}
#outline()

Today a poor guy writes the above code, and receives a misleading error message:

Missing argument: self

Image

Noticing prefix and inner are positional, he/she removes the parameter names, and get another nonsense:

Expected outline entry

Image

The correct usage is as follows (already included in the docs, but was ignored because it's far above):

#show outline.entry: it => {
  it.indented(
    it.prefix(),
    it.body(),
    gap: 12em,
  )
}

Another working solution:

#show outline.entry: it => {
  outline.entry.indented(
    it,
    it.prefix(),
    it.body(),
    gap: 12em,
  )
}

Case 2: selector.or

Many people don't know selector.or can be used as a plain function.

#selector(a).or(b, c) // okay
#selector.or(a, b, c) // also okay, but not everyone knows

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 $scripting/#methods documentation and compare the outline.entry.indented and selector.or reference examples. Explain how self is interpreted in reference pages and make the method and plain-function forms understandable; consider the reported error-message improvement separately because the issue does not establish whether it is feasible.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.