Touch up docs

crates/typst-library/src/compute/construct.rs

@@ -345,7 +345,7 @@ pub fn datetime_today(
 /// #square(
 ///   fill: cmyk(27%, 0%, 3%, 5%)
 /// )
-/// ````
+/// ```
 ///
 /// Display: CMYK
 /// Category: construct
@@ -384,13 +384,14 @@ pub fn color_module() -> Module {
 
 /// Create a color by mixing two or more colors.
 ///
-/// ## Example
+/// ## Example { #example }
 /// ```example
-/// #color.mix(red, green)
+/// #set block(height: 20pt, width: 100%)
-/// #color.mix(red, green, white)
+/// #block(fill: color.mix(red, blue))
-/// #color.mix(red, green, space: "srgb")
+/// #block(fill: color.mix(red, blue, space: "srgb"))
-/// #color.mix((red, 30%), (green, 70%))
+/// #block(fill: color.mix((red, 70%), (blue, 30%)))
-/// ````
+/// #block(fill: color.mix(red, blue, white))
+/// ```
 ///
 /// _Note:_ This function must be specified as `color.mix`, not just `mix`.
 /// Currently, `color` is a module, but it is designed to be forward compatible
@@ -402,6 +403,9 @@ pub fn color_module() -> Module {
 pub fn mix(
     /// The colors, optionally with weights, specified as a pair (array of
     /// length two) of color and weight (float or ratio).
+    ///
+    /// The weights do not need to add to `{100%}`, they are relative to the
+    /// sum of all weights.
     #[variadic]
     colors: Vec<WeightedColor>,
     /// The color space to mix in. By default, this happens in a perceptual

crates/typst-library/src/layout/align.rs

@@ -33,8 +33,8 @@ pub struct AlignElem {
     /// - `horizon`
     /// - `bottom`
     ///
-    /// You may use the `axis` method on a single-axis alignment to obtain
+    /// You can use the `axis` method on a single-axis alignment to obtain
-    /// whether it is `{"horizontal"}` or `{"vertical"}`. You may also use the
+    /// whether it is `{"horizontal"}` or `{"vertical"}`. You can also use the
     /// `inv` method to obtain its inverse alignment. For example,
     /// `{top.axis()}` is `{"vertical"}`, while `{top.inv()}` is equal to
     /// `{bottom}`.
@@ -43,12 +43,11 @@ pub struct AlignElem {
     /// the `+` operator to get a `2d alignment`. For example, `top + right`
     /// aligns the content to the top right corner.
     ///
-    /// For 2d alignments, you may use the `x` and `y` fields to access their
+    /// For 2d alignments, the `x` and `y` fields hold their horizontal and
-    /// horizontal and vertical components, respectively. Additionally, you may
+    /// vertical components, respectively. Additionally, you can use the `inv`
-    /// use the `inv` method to obtain a 2d alignment with both components
+    /// method to obtain a 2d alignment with both components inverted. For
-    /// inverted. For instance, `{(top + right).x}` is `right`,
+    /// instance, `{(top + right).x}` is `right`, `{(top + right).y}` is `top`,
-    /// `{(top + right).y}` is `top`, and `{(top + right).inv()}` is equal to
+    /// and `{(top + right).inv()}` is equal to `bottom + left`.
-    /// `bottom + left`.
     ///
     /// ```example
     /// #set page(height: 6cm)

crates/typst-library/src/layout/enum.rs

@@ -56,8 +56,8 @@ use super::GridLayouter;
 ///   numbered enumeration item.
 ///
 /// Enumeration items can contain multiple paragraphs and other block-level
-/// content. All content that is indented more than an item's plus sign or dot
+/// content. All content that is indented more than an item's marker becomes
-/// becomes part of that item.
+/// part of that item.
 ///
 /// Display: Numbered List
 /// Category: layout

crates/typst-library/src/layout/list.rs

@@ -32,7 +32,7 @@ use super::GridLayouter;
 /// This functions also has dedicated syntax: Start a line with a hyphen,
 /// followed by a space to create a list item. A list item can contain multiple
 /// paragraphs and other block-level content. All content that is indented
-/// more than an item's hyphen becomes part of that item.
+/// more than an item's marker becomes part of that item.
 ///
 /// Display: Bullet List
 /// Category: layout

crates/typst-library/src/layout/stack.rs

@@ -27,11 +27,11 @@ pub struct StackElem {
     /// - `{ttb}`: Top to bottom.
     /// - `{btt}`: Bottom to top.
     ///
-    /// You may use the `start` and `end` methods to obtain the initial and
+    /// You cab use the `start` and `end` methods to obtain the initial and
-    /// final points (respectively) of a direction, as `alignment`. You may
+    /// final points (respectively) of a direction, as `alignment`. You can also
-    /// also use the `axis` method to obtain whether a direction is
+    /// use the `axis` method to determine whether a direction is
-    /// `{"horizontal"}` or `{"vertical"}`. Finally, the `inv` method returns
+    /// `{"horizontal"}` or `{"vertical"}`. The `inv` method returns a
-    /// its inverse direction.
+    /// direction's inverse direction.
     ///
     /// For example, `{ttb.start()}` is `top`, `{ttb.end()}` is `bottom`,
     /// `{ttb.axis()}` is `{"vertical"}` and `{ttb.inv()}` is equal to `btt`.

crates/typst-library/src/math/class.rs

@@ -3,11 +3,16 @@ use super::*;
 /// Forced use of a certain math class.
 ///
 /// This is useful to treat certain symbols as if they were of a different
-/// class, e.g. to make text behave like a binary operator.
+/// class, e.g. to make a symbol behave like a relation.
 ///
-/// # Example
+/// ## Example { #example }
 /// ```example
-/// $x class("relation", "<=") 5$
+/// #let loves = math.class(
+///   "relation",
+///   sym.suit.heart,
+/// )
+///
+/// $x loves y and y loves 5$
 /// ```
 ///
 /// Display: Class

crates/typst-library/src/meta/figure.rs

@@ -217,7 +217,7 @@ impl Synthesize for FigureElem {
             VerticalAlign(GenAlign::Specific(match self.caption_pos(styles) {
                 VerticalAlign(GenAlign::Specific(Align::Top)) => Align::Top,
                 VerticalAlign(GenAlign::Specific(Align::Bottom)) => Align::Bottom,
-                _ => bail!(self.span(), "caption-position can only be top or bottom"),
+                _ => bail!(self.span(), "caption-pos can only be top or bottom"),
             }));
 
         // Resolve the supplement.

crates/typst-library/src/meta/metadata.rs

@@ -2,19 +2,14 @@ use crate::prelude::*;
 
 /// Exposes a value to the query system without producing visible content.
 ///
-/// This element can be queried for with the [`query`]($func/query) function and
+/// This element can be retrieved with the [`query`]($func/query) function and
-/// the command line `typst query` command. Its purpose is to expose an
+/// from the command with [`typst query`]($reference/meta/query/#cli-queries).
-/// arbitrary value to the introspection system. To identify a metadata value
+/// Its purpose is to expose an arbitrary value to the introspection system. To
-/// among others, you can attach a [`label`]($type/label) to it and query for
+/// identify a metadata value among others, you can attach a
-/// that label.
+/// [`label`]($type/label) to it and query for that label.
 ///
-/// ```typ
+/// The `metadata` element is especially useful for command line queries because
-/// #metadata("This is a note") <note>
+/// it allows you to expose arbitrary values to the outside world.
-/// ```
-///
-/// ## Within Typst: `query` function { #within-typst }
-/// Metadata can be retrieved from with the [`query`]($func/query) function
-/// (like other elements):
 ///
 /// ```example
 /// // Put metadata somewhere.
@@ -26,45 +21,6 @@ use crate::prelude::*;
 /// })
 /// ```
 ///
-/// ## Outside of Typst: `typst query` command { #outside-of-typst }
-/// You can also retrieve the metadata from the command line with the
-/// `typst query` command. This command executes an arbitrary query on the
-/// document and returns the resulting elements in serialized form.
-///
-/// The `metadata` element is especially useful for command line queries because
-/// it allows you to expose arbitrary values to the outside world. However,
-/// `typst query` also works with other elements `metadata` and complex
-/// [selectors]($type/selector) like `{heading.where(level: 1)}`.
-///
-/// ```sh
-/// $ typst query example.typ "<note>"
-/// [
-///   {
-///     "func": "metadata",
-///     "value": "This is a note",
-///     "label": "<note>"
-///   }
-/// ]
-/// ```
-///
-/// Frequently, you're interested in only one specific field of the resulting
-/// elements. In the case of the `metadata` element, the `value` field is the
-/// interesting one. You can extract just this field with the `--field`
-/// argument.
-///
-/// ```sh
-/// $ typst query example.typ "<note>" --field value
-/// ["This is a note"]
-/// ```
-///
-/// If you are interested in just a single element, you can use the `--one`
-/// flag to extract just it.
-///
-/// ```sh
-/// $ typst query example.typ "<note>" --field value --one
-/// "This is a note"
-/// ```
-///
 /// Display: Metadata
 /// Category: meta
 #[element(Behave, Show, Locatable)]

crates/typst-library/src/meta/query.rs

@@ -3,12 +3,9 @@ use crate::prelude::*;
 /// Finds elements in the document.
 ///
 /// The `query` functions lets you search your document for elements of a
-/// particular type or with a particular label.
+/// particular type or with a particular label. To use it, you first need to
-///
+/// retrieve the current document location with the [`locate`]($func/locate)
-/// To use it, you first need to retrieve the current document location with the
+/// function.
-/// [`locate`]($func/locate) function. You can then decide whether you want to
-/// find all elements, just the ones before that location, or just the ones
-/// after it.
 ///
 /// ## Finding elements { #finding-elements }
 /// In the example below, we create a custom page header that displays the text
@@ -89,12 +86,45 @@ use crate::prelude::*;
 /// })
 /// ```
 ///
-/// ## Migration Hints { #migration-hints }
+/// ## Command line queries { #command-line-queries }
-/// The `before` and `after` arguments have been removed in version 0.3.0. You
+/// You can also perform queries from the command line with the `typst query`
-/// can now use flexible selector combinator methods instead. For example,
+/// command. This command executes an arbitrary query on the document and
-/// `query(heading, before: loc)` becomes `query(heading.before(loc), loc)`.
+/// returns the resulting elements in serialized form. Consider the following
-/// Please refer to the [selector documentation]($type/selector) for more
+/// `example.typ` file which contains some invisible [metadata]($func/metadata):
-/// details.
+///
+/// ```typ
+/// #metadata("This is a note") <note>
+/// ```
+///
+/// You can execute a query on it as follows using Typst's CLI:
+/// ```sh
+/// $ typst query example.typ "<note>"
+/// [
+///   {
+///     "func": "metadata",
+///     "value": "This is a note",
+///     "label": "<note>"
+///   }
+/// ]
+/// ```
+///
+/// Frequently, you're interested in only one specific field of the resulting
+/// elements. In the case of the `metadata` element, the `value` field is the
+/// interesting one. You can extract just this field with the `--field`
+/// argument.
+///
+/// ```sh
+/// $ typst query example.typ "<note>" --field value
+/// ["This is a note"]
+/// ```
+///
+/// If you are interested in just a single element, you can use the `--one`
+/// flag to extract just it.
+///
+/// ```sh
+/// $ typst query example.typ "<note>" --field value --one
+/// "This is a note"
+/// ```
 ///
 /// Display: Query
 /// Category: meta

crates/typst-library/src/text/mod.rs

@@ -265,31 +265,6 @@ pub struct TextElem {
     #[default(BottomEdge::Metric(BottomEdgeMetric::Baseline))]
     pub bottom_edge: BottomEdge,
 
-    /// The OpenType writing script setting.
-    ///
-    /// The combination of `{script}` and `{lang}` determine how
-    /// font features, such as glyph substitution, are implemented.
-    /// Frequently the value is a modified (all-lowercase) ISO 15924 script identifier, and
-    /// the `math` writing script is used for features appropriate
-    /// for mathematical symbols.
-    ///
-    /// When set to `{auto}`, the default and recommended setting,
-    /// an appropriate script is chosen for each block of characters
-    /// sharing a common Unicode script property.
-    ///
-    /// ```example
-    /// #let scedilla = [Ş]
-    /// #set text(font: "Linux Libertine", size: 20pt)
-    /// #scedilla // S with a cedilla
-    ///
-    /// #set text(script: "latn", lang: "ro")
-    /// #scedilla // S with a subscript comma
-    ///
-    /// #set text(script: "grek", lang: "ro")
-    /// #scedilla // S with a cedilla
-    /// ```
-    pub script: Smart<WritingScript>,
-
     /// An [ISO 639-1/2/3 language code.](https://en.wikipedia.org/wiki/ISO_639)
     ///
     /// Setting the correct language affects various parts of Typst:
@@ -315,6 +290,35 @@ pub struct TextElem {
     /// This lets the text processing pipeline make more informed choices.
     pub region: Option<Region>,
 
+    /// The OpenType writing script.
+    ///
+    /// The combination of `{lang}` and `{script}` determine how font features,
+    /// such as glyph substitution, are implemented. Frequently the value is a
+    /// modified (all-lowercase) ISO 15924 script identifier, and the `math`
+    /// writing script is used for features appropriate for mathematical
+    /// symbols.
+    ///
+    /// When set to `{auto}`, the default and recommended setting, an
+    /// appropriate script is chosen for each block of characters sharing a
+    /// common Unicode script property.
+    ///
+    /// ```example
+    /// #set text(
+    ///   font: "Linux Libertine",
+    ///   size: 20pt,
+    /// )
+    ///
+    /// #let scedilla = [Ş]
+    /// #scedilla // S with a cedilla
+    ///
+    /// #set text(lang: "ro", script: "latn")
+    /// #scedilla // S with a subscript comma
+    ///
+    /// #set text(lang: "ro", script: "grek")
+    /// #scedilla // S with a cedilla
+    /// ```
+    pub script: Smart<WritingScript>,
+
     /// The dominant direction for text and inline objects. Possible values are:
     ///
     /// - `{auto}`: Automatically infer the direction from the `lang` property.

crates/typst-library/src/text/raw.rs

@@ -135,7 +135,8 @@ pub struct RawElem {
     pub align: HorizontalAlign,
 
     /// One or multiple additional syntax definitions to load. The syntax
-    /// definitions should be in the `sublime-syntax` file format.
+    /// definitions should be in the
+    /// [`sublime-syntax` file format](https://www.sublimetext.com/docs/syntax.html).
     ///
     /// ````example
     /// #set raw(syntaxes: "SExpressions.sublime-syntax")
@@ -161,11 +162,25 @@ pub struct RawElem {
     #[fold]
     pub syntaxes_data: Vec<Bytes>,
 
-    /// The theme to use for syntax highlighting. Theme files should be in the in the
+    /// The theme to use for syntax highlighting. Theme files should be in the
-    /// `tmTheme` file format.
+    /// in the [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html).
+    ///
+    /// Applying a theme only affects the color of specifically highlighted
+    /// text. It does not consider the theme's foreground and background
+    /// properties, so that you retain control over the color of raw text. You
+    /// can apply the foreground color yourself with the [`text`]($func/text)
+    /// function and the background with a [filled block]($func/block.fill). You
+    /// could also use the [`xml`]($func/xml) function to extract these
+    /// properties from the theme.
     ///
     /// ````example
     /// #set raw(theme: "halcyon.tmTheme")
+    /// #show raw: it => block(
+    ///   fill: rgb("#1d2433"),
+    ///   inset: 8pt,
+    ///   radius: 5pt,
+    ///   text(fill: rgb("#a2aabc"), it)
+    /// )
     ///
     /// ```typ
     /// = Chapter 1

crates/typst-library/src/visualize/line.rs

@@ -69,10 +69,10 @@ pub struct LineElem {
     ///       the array above), and `phase` (of type [length]($type/length)),
     ///       which defines where in the pattern to start drawing.
     ///
-    /// Note that, for any `stroke` object, you may access any of the fields
+    /// On a `stroke` object, you can access any of the fields mentioned in the
-    /// mentioned in the dictionary format above. For example,
+    /// dictionary format above. For example, `{(2pt + blue).thickness}` is
-    /// `{(2pt + blue).thickness}` is `{2pt}`, `{(2pt + blue).miter-limit}` is
+    /// `{2pt}`, `{(2pt + blue).miter-limit}` is `{4.0}` (the default), and so
-    /// `{4.0}` (the default), and so on.
+    /// on.
     ///
     /// ```example
     /// #set line(length: 100%)

crates/typst-macros/src/element.rs

@@ -433,7 +433,7 @@ fn create_param_info(field: &Field) -> TokenStream {
         }
     }));
     let ty = if *variadic {
-        quote! { <#ty as ::typst::eval::Variadics>::Inner }
+        quote! { <#ty as ::typst::eval::Container>::Inner }
     } else {
         quote! { #ty }
     };

crates/typst-macros/src/func.rs

@@ -210,7 +210,12 @@ fn create(func: &Func, item: &syn::ItemFn) -> TokenStream {
 fn create_param_info(param: &Param) -> TokenStream {
     let Param { name, docs, named, variadic, ty, default, .. } = param;
     let positional = !named;
-    let required = default.is_none();
+    let required = !named && default.is_none();
+    let ty = if *variadic || (*named && default.is_none()) {
+        quote! { <#ty as ::typst::eval::Container>::Inner }
+    } else {
+        quote! { #ty }
+    };
     let default = quote_option(&default.as_ref().map(|_default| {
         quote! {
             || {
@@ -219,11 +224,6 @@ fn create_param_info(param: &Param) -> TokenStream {
             }
         }
     }));
-    let ty = if *variadic {
-        quote! { <#ty as ::typst::eval::Variadics>::Inner }
-    } else {
-        quote! { #ty }
-    };
     quote! {
         ::typst::eval::ParamInfo {
             name: #name,

crates/typst/src/eval/cast.rs

@@ -281,13 +281,17 @@ impl Add for CastInfo {
     }
 }
 
-/// A container for a variadic argument.
+/// A container for an argument.
-pub trait Variadics {
+pub trait Container {
     /// The contained type.
     type Inner;
 }
 
-impl<T> Variadics for Vec<T> {
+impl<T> Container for Option<T> {
+    type Inner = T;
+}
+
+impl<T> Container for Vec<T> {
     type Inner = T;
 }
 
@@ -335,14 +339,24 @@ cast! {
         MathClass::Vary => "vary",
         MathClass::Special => "special",
     }),
+    /// The default class for non-special things.
     "normal" => MathClass::Normal,
-    "binary" => MathClass::Binary,
+    /// Punctuation, e.g. a comma.
-    "closing" => MathClass::Closing,
-    "fence" => MathClass::Fence,
-    "large" => MathClass::Large,
-    "opening" => MathClass::Opening,
     "punctuation" => MathClass::Punctuation,
+    /// An opening delimiter, e.g. `(`.
+    "opening" => MathClass::Opening,
+    /// A closing delimiter, e.g. `)`.
+    "closing" => MathClass::Closing,
+    /// A delimiter that is the same on both sides, e.g. `|`.
+    "fence" => MathClass::Fence,
+    /// A large operator like `sum`.
+    "large" => MathClass::Large,
+    /// A relation like `=` or `prec`.
     "relation" => MathClass::Relation,
+    /// A unary operator like `not`.
     "unary" => MathClass::Unary,
+    /// A binary operator like `times`.
+    "binary" => MathClass::Binary,
+    /// An operator that can be both unary or binary like `+`.
     "vary" => MathClass::Vary,
 }

crates/typst/src/eval/mod.rs

@@ -43,7 +43,7 @@ pub use self::array::{array, Array};
 pub use self::auto::AutoValue;
 pub use self::bytes::Bytes;
 pub use self::cast::{
-    cast, Cast, CastInfo, FromValue, IntoResult, IntoValue, Never, Reflect, Variadics,
+    cast, Cast, CastInfo, Container, FromValue, IntoResult, IntoValue, Never, Reflect,
 };
 pub use self::datetime::Datetime;
 pub use self::dict::{dict, Dict};

docs/reference/types.md

@@ -87,9 +87,9 @@ Typst supports the following length units:
 
 A length has the following fields:
 
-- `em`: The amount of `em` units in this length, as a [float]($type/float).
 - `abs`: A length with just the absolute component of the current length
 (that is, excluding the `em` component).
+- `em`: The amount of `em` units in this length, as a [float]($type/float).
 
 You can multiply lengths with and divide them by integers and floats.
 
@@ -110,38 +110,34 @@ You can multiply lengths with and divide them by integers and floats.
 ### pt()
 Converts this length to points.
 
-Fails with an error if this length has non-zero `em` units
+Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
-(such as `5em + 2pt` instead of just `2pt`). Use the `abs`
+instead of just `2pt`). Use the `abs` field (such as in `(5em + 2pt).abs.pt()`)
-field (such as in `(5em + 2pt).abs.pt()`) to ignore the
+to ignore the `em` component of the length (thus converting only its absolute
-`em` component of the length (thus converting only its
+component).
-absolute component).
 
 - returns: float
 
 ### mm()
 Converts this length to millimeters.
 
-Fails with an error if this length has non-zero `em` units
+Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
-(such as `5em + 2pt` instead of just `2pt`). See the
+instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
-[`pt()`]($type/float.pt) method for more info.
 
 - returns: float
 
 ### cm()
 Converts this length to centimeters.
 
-Fails with an error if this length has non-zero `em` units
+Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
-(such as `5em + 2pt` instead of just `2pt`). See the
+instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
-[`pt()`]($type/float.pt) method for more info.
 
 - returns: float
 
 ### inches()
 Converts this length to inches.
 
-Fails with an error if this length has non-zero `em` units
+Fails with an error if this length has non-zero `em` units (such as `5em + 2pt`
-(such as `5em + 2pt` instead of just `2pt`). See the
+instead of just `2pt`). See the [`pt`]($type/float.pt) method for more info.
-[`pt()`]($type/float.pt) method for more info.
 
 - returns: float
 
@@ -235,7 +231,8 @@ Returns the constructor function for this color's kind
 ([`rgb`]($func/rgb), [`cmyk`]($func/cmyk) or [`luma`]($func/luma)).
 
 ```example
-#{cmyk(1%, 2%, 3%, 4%).kind() == cmyk}
+#let color = cmyk(1%, 2%, 3%, 4%)
+#(color.kind() == cmyk)
 ```
 
 - returns: function
@@ -273,9 +270,10 @@ of [integers]($type/integer).
 - returns: array
 
 ### cmyk()
-Converts this color to Digital CMYK and returns its components (C, M, Y, K) as an
+Converts this color to Digital CMYK and returns its components (C, M, Y, K) as
-array of [ratio]($type/ratio). Note that this function will throw an error when
+an array of [ratios]($type/ratio). Note that this function will throw an error
-applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not available.
+when applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not
+available.
 
 - returns: array