From 2d16f9434f46ab591cede54def23ae4bc477b668 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Mon, 20 Mar 2023 21:56:32 +0100 Subject: Documentation for citation, bibliography, and content --- docs/src/reference/details.yml | 15 ++++++-- docs/src/reference/scripting.md | 3 +- docs/src/reference/styling.md | 24 ++++++------ docs/src/reference/types.md | 81 ++++++++++++++++++++++++++++++----------- 4 files changed, 86 insertions(+), 37 deletions(-) (limited to 'docs/src') diff --git a/docs/src/reference/details.yml b/docs/src/reference/details.yml index 789e5390..25799402 100644 --- a/docs/src/reference/details.yml +++ b/docs/src/reference/details.yml @@ -95,10 +95,17 @@ visualize: | be in the future. meta: | - Document structuring and metadata setup. + Document structuring, introspection, and metadata configuration. - Here, you can find functions to structure your document and configure its - metadata. + Here, you can find functions to structure your document and interact with that + structure. This includes section headings and figures, bibliography + management, cross-referencing and more. + + Moreover, this category is home to Typst's introspection capabilities: With + the `counter` function, you can access and manipulate page, section, figure, + and equation counters or create custom ones. And the `query` function lets you + search for elements in the document to construct things like a list of + figures or headers which show the current chapter title. symbols: | These two modules give names to symbols and emoji to make them easy to insert @@ -114,6 +121,8 @@ sym: | [formulas]($category/math), these symbols can be used without the `#sym.` prefix. + The `d` in an integral's `dx` can be written as `[$dif x$]`. + emoji: | Named emoji. diff --git a/docs/src/reference/scripting.md b/docs/src/reference/scripting.md index 1aa399d1..15e4be91 100644 --- a/docs/src/reference/scripting.md +++ b/docs/src/reference/scripting.md @@ -178,8 +178,7 @@ can be either: - a [dictionary]($type/dictionary) that has the specified key, - a [symbols]($type/symbol) that has the specified modifier, - a [module]($type/module) containing the specified definition, -- [content]($type/content) that exposes the specified field. Most elements - expose some or all of the non-settable arguments passed to them as fields. +- [content]($type/content) that has the specified field. ```example #let dict = (greet: "Hello") diff --git a/docs/src/reference/styling.md b/docs/src/reference/styling.md index 4997bf19..a3cc3c2e 100644 --- a/docs/src/reference/styling.md +++ b/docs/src/reference/styling.md @@ -13,15 +13,17 @@ of elements. ## Set rules { #set-rules } With set rules, you can customize the appearance of elements. They are written as a [function call]($type/function) to the respective function preceded by the -`{set}` keyword (or `[#set]` in markup). Only settable parameters must be -provided as arguments. Refer to each function's documentation for a list of -settable parameters. In the example below, we use two set rules to change the -[font family]($func/text.family) and -[heading numbering]($func/heading.numbering) style. +`{set}` keyword (or `[#set]` in markup). Only optional parameters of that +function can be provided to the set rule. Refer to each function's documentation +to see which parameters are optional. In the example below, we use two set rules +to change the [font family]($func/text.family) and +[heading numbering]($func/heading.numbering). ```example -#set text(font: "New Computer Modern") #set heading(numbering: "I.") +#set text( + font: "New Computer Modern" +) = Introduction With set rules, you can style @@ -35,9 +37,10 @@ your document. Below, we use a content block to scope the list styling to one particular list. ```example -This list is affected: -#[#set list(marker: [--]) - - Dash] +This list is affected: #[ + #set list(marker: [--]) + - Dash +] This one is not: - Bullet @@ -87,8 +90,7 @@ fantasy encyclopedia. #set align(center) #set text(font: "Inria Serif") \~ #emph(it.body) - #(counter(heading) - .display(it.numbering)) \~ + #counter(heading).display() \~ ] = Dragon diff --git a/docs/src/reference/types.md b/docs/src/reference/types.md index a64f4eb3..3a768d27 100644 --- a/docs/src/reference/types.md +++ b/docs/src/reference/types.md @@ -379,18 +379,16 @@ the resulting parts. - returns: array # Content -Representation of text, elements, and more. +Representation of document content. This type is at the heart of Typst. All markup you write and most -[functions]($type/function) you call produce content values. You -can create a content value by enclosing markup in square brackets. This is also -how you pass content to functions. Typst does not allow you to peek into -content, but you can affect its appearance in various ways using set and show -rules. See the chapter on [styling]($styling) for more details. +[functions]($type/function) you call produce content values. You can create a +content value by enclosing markup in square brackets. This is also how you pass +content to functions. ```example -#type([*Hello!*]) \ -#strong[Hello!] +Type of *Hello!* is +#type([*Hello!*]) ``` Content can be added with the `+` operator, @@ -398,21 +396,62 @@ Content can be added with the `+` operator, integers. Wherever content is expected, you can also pass a [string]($type/string) or `{none}`. -### Reactivity -Content is reactive to the styles that are active where it is inserted. -When you write a set or show rule, content that was _created_ before the show -rule is stilled affected by the show rule if it is _inserted_ after the show -rule. +## Representation +Content consists of elements with fields. When constructing an element with +its _element function,_ you provide these fields as arguments and when you have +a content value, you can access its fields with +[field access syntax]($scripting/#field-access). -```example -// Content is created here. -#let mytext = [= A heading] +Some fields are required: These must be provided when constructing an element +and as a consequence, they are always available through field access on content +of that type. Required fields are marked as such in the documentation. -// But still affected by the -// styles that are active here. -#show heading: set text(green) -#mytext -``` +Most fields are optional: Like required fields, they can be passed to the +element function to configure them for a single element. However, these can also +be configured with [set rules]($styling/#set-rules) to apply them to all +elements within a scope. Optional fields are only available with field access +syntax when they are were explicitly passed to the element function, not when +they result from a set rule. + +Each element has a default appearance. However, you can also completely +customize its appearance with a [show rule]($styling/#show-rules). The show rule +is passed the element. It can access the element's field and produce arbitrary +content from it. + +In the web app, you can hover over a content variable to see exactly which +elements the content is composed of and what fields they have. Alternatively, +you can inspect the output of the [`repr`]($func/repr) function. + +## Methods +### func() +The content's element function. This function can be used to create the element +contained in this content. It can be used in set and show rules for the element. +Can be compared with global functions to check whether you have a specific +kind of element. + +- returns: function + +### has() +Whether the content has the specified field. + +- field: string (positional, required) + The field to look for. +- returns: boolean + +### at() +Access the specified field on the content. + +- field: string (positional, required) + The field to access. +- returns: any + +### location() +The location of the content. This is only available on content returned by +[query]($func/query), for other content it will fail with an error. The +resulting location can be used with [counters]($func/counter), +[state]($func/state) and [queries]($func/query). + +- returns: location # Array A sequence of values. -- cgit v1.2.3