From ae89b51389ec1e16382f1bf0003be104b1394b74 Mon Sep 17 00:00:00 2001 From: Ullrich Koethe Date: Thu, 6 Mar 2025 10:23:43 +0100 Subject: [PATCH] Added section 'The computational model behind typst' --- docs/reference/language/styling.md | 50 ++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/reference/language/styling.md b/docs/reference/language/styling.md index b0b7ab711..cbfff279e 100644 --- a/docs/reference/language/styling.md +++ b/docs/reference/language/styling.md @@ -10,6 +10,56 @@ might not be a built-in property for everything you wish to do. For this reason, Typst further supports _show rules_ that can completely redefine the appearance of elements. +## The computational model behind typst + +Typesetting is controlled by hundreds of parameters, from page margins to font sizes to numbering conventions. Managing this mess is a major focus of every typesetting system. The first step is to arrange these properties into related groups. In typst, these groups are called _element functions_ (EFs), for example `text` for font properties (typeface, size, color etc.), `par` for paragraphs (line spacing, alignment, indentation etc.), and `figure` (placement rules, captioning, and numbering of tables and figures). A complete list of the available element functions is **where??**. The term _functions_ indicates that these entities do not merely act as passive property containers, but can actively process content (usually provided in the function's `body` parameter) according to the present parameter settings. + +Since different parts of the document need different settings for the same parameters (e.g. the font size in headings, plain text, and footnotes), each element function type exists in multiple instances. On the other hand, different EF types must interact to typeset a particular piece of content. You can imagine this as an _ensemble_ of EMs playing together to create the desired output. For example, math rendering requires the `math.equation` EF for equation-specific information, but also `text` for the font, `par` for line spacing, and `block` to control potential page breaks. A complete table of which EFs interact in which situation can be found **where??**. + +The set of active EFs changes frequently during the processing of your document. To provide consistent access to precisely the members of the active ensemble at a given point, typst uses the concept of a _context_ (see section [Context]($context) for detailed information). By default, typst expressions refer to the context "here" (i.e. to the moment when processing reaches the current document location), but you can specify and access many other processing stages as well, e.g. "whenever an equation will be rendered in the future" or "upon creation of the table-of-contents". By accessing element functions via contexts, it is guaranteed that parameters are manipulated in a coordinated way and in the appriate instances of the involved EFs. + +There are three fundamental methods to modify parameters: +- function calls, e.g. `#text(size: 25pt, [Hello]))` Use 25pt font to typeset just the given content, here 'Hello'. +- set rules, e.g. `#set text(size: 25pt)` Instruct the currently active `text` EF to use 25pt font until further notice. +- show rules, e.g. `#show math.equation: text.with(size: 25pt)` Typeset subsequent equations with 25pt font. + +Show rules are the most powerful (and most complicated), because they give you access to an entire active ensemble of EFs. Parameter modifications like the ones above have generally a _limited lifetime_: A modification passed as a function argument expires when the function completes, and the original parameter value is restored. Set and show rules are active until the end of the enclosing scope, i.e. until the next closing bracket or brace: + +```example +#set text(size: 11pt) // #1 +this is 11pt \ +#[ // open a new scope + still 11pt \ + #set text(size: 25pt) // #2 + now 25pt \ +] // end of scope, #2 expires +// #1 reactivated +again 11pt +``` + +When several rules refering to the same parameter occur in the same scope, each one overrides the previous specification. Modifications applied outside of any scope, i.e. at the top level of the document, remain active during the entire typesetting process unless they are explicitly overridden. These global settings are usually provided by a style template. + +Scopes give rise to a common pitfall when you want to apply rules conditionally. The following code has no effect: + +```typ +#if some-condition() { + set text(size: 11pt) // #1 +} else { // end of scope, #1 expires + set text(size: 25pt) // #2 +} // end of scope, #2 expires +// original behavior restored +``` + +You must use a postfix conditional instead + +```typ +#set text(size: 11pt) if some-condition() +#set text(size: 25pt) if not some-condition() +// no scope, modification is active +``` + +Now, let's delve into the details of set and show rules. + ## Set rules With set rules, you can customize the appearance of elements. They are written as a [function call]($function) to an [element