diff --git a/crates/typst-library/src/compute/construct.rs b/crates/typst-library/src/compute/construct.rs index 841bf4069..0a6f24a56 100644 --- a/crates/typst-library/src/compute/construct.rs +++ b/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) -/// #color.mix(red, green, white) -/// #color.mix(red, green, space: "srgb") -/// #color.mix((red, 30%), (green, 70%)) -/// ```` +/// #set block(height: 20pt, width: 100%) +/// #block(fill: color.mix(red, blue)) +/// #block(fill: color.mix(red, blue, space: "srgb")) +/// #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, /// The color space to mix in. By default, this happens in a perceptual diff --git a/crates/typst-library/src/layout/align.rs b/crates/typst-library/src/layout/align.rs index fecc7e336..5f7e8bc04 100644 --- a/crates/typst-library/src/layout/align.rs +++ b/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 - /// whether it is `{"horizontal"}` or `{"vertical"}`. You may also use the + /// You can use the `axis` method on a single-axis alignment to obtain + /// 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 - /// horizontal and vertical components, respectively. Additionally, you may - /// use the `inv` method to obtain a 2d alignment with both components - /// inverted. For instance, `{(top + right).x}` is `right`, - /// `{(top + right).y}` is `top`, and `{(top + right).inv()}` is equal to - /// `bottom + left`. + /// For 2d alignments, the `x` and `y` fields hold their horizontal and + /// vertical components, respectively. Additionally, you can use the `inv` + /// method to obtain a 2d alignment with both components inverted. For + /// instance, `{(top + right).x}` is `right`, `{(top + right).y}` is `top`, + /// and `{(top + right).inv()}` is equal to `bottom + left`. /// /// ```example /// #set page(height: 6cm) diff --git a/crates/typst-library/src/layout/enum.rs b/crates/typst-library/src/layout/enum.rs index d66477fc4..3d0b09738 100644 --- a/crates/typst-library/src/layout/enum.rs +++ b/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 -/// becomes part of that item. +/// content. All content that is indented more than an item's marker becomes +/// part of that item. /// /// Display: Numbered List /// Category: layout diff --git a/crates/typst-library/src/layout/list.rs b/crates/typst-library/src/layout/list.rs index e39ec3f50..4a7c40b70 100644 --- a/crates/typst-library/src/layout/list.rs +++ b/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 diff --git a/crates/typst-library/src/layout/stack.rs b/crates/typst-library/src/layout/stack.rs index 8d536638b..52a2f289d 100644 --- a/crates/typst-library/src/layout/stack.rs +++ b/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 - /// final points (respectively) of a direction, as `alignment`. You may - /// also use the `axis` method to obtain whether a direction is - /// `{"horizontal"}` or `{"vertical"}`. Finally, the `inv` method returns - /// its inverse direction. + /// You cab use the `start` and `end` methods to obtain the initial and + /// final points (respectively) of a direction, as `alignment`. You can also + /// use the `axis` method to determine whether a direction is + /// `{"horizontal"}` or `{"vertical"}`. The `inv` method returns a + /// 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`. diff --git a/crates/typst-library/src/math/class.rs b/crates/typst-library/src/math/class.rs index 0d6a370b7..69635c629 100644 --- a/crates/typst-library/src/math/class.rs +++ b/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 diff --git a/crates/typst-library/src/meta/figure.rs b/crates/typst-library/src/meta/figure.rs index d1c58cd0f..d63ae3a8e 100644 --- a/crates/typst-library/src/meta/figure.rs +++ b/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. diff --git a/crates/typst-library/src/meta/metadata.rs b/crates/typst-library/src/meta/metadata.rs index eed4c71f6..ed0d19864 100644 --- a/crates/typst-library/src/meta/metadata.rs +++ b/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 -/// the command line `typst query` command. Its purpose is to expose an -/// arbitrary value to the introspection system. To identify a metadata value -/// among others, you can attach a [`label`]($type/label) to it and query for -/// that label. +/// This element can be retrieved with the [`query`]($func/query) function and +/// from the command with [`typst query`]($reference/meta/query/#cli-queries). +/// Its purpose is to expose an arbitrary value to the introspection system. To +/// identify a metadata value among others, you can attach a +/// [`label`]($type/label) to it and query for that label. /// -/// ```typ -/// #metadata("This is a note") -/// ``` -/// -/// ## Within Typst: `query` function { #within-typst } -/// Metadata can be retrieved from with the [`query`]($func/query) function -/// (like other elements): +/// The `metadata` element is especially useful for command line queries because +/// it allows you to expose arbitrary values to the outside world. /// /// ```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 "" -/// [ -/// { -/// "func": "metadata", -/// "value": "This is a note", -/// "label": "" -/// } -/// ] -/// ``` -/// -/// 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 "" --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 "" --field value --one -/// "This is a note" -/// ``` -/// /// Display: Metadata /// Category: meta #[element(Behave, Show, Locatable)] diff --git a/crates/typst-library/src/meta/query.rs b/crates/typst-library/src/meta/query.rs index 826b812ea..a644000d7 100644 --- a/crates/typst-library/src/meta/query.rs +++ b/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. -/// -/// To use it, you first need to retrieve the current document location with the -/// [`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. +/// particular type or with a particular label. To use it, you first need to +/// retrieve the current document location with the [`locate`]($func/locate) +/// function. /// /// ## 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 } -/// The `before` and `after` arguments have been removed in version 0.3.0. You -/// can now use flexible selector combinator methods instead. For example, -/// `query(heading, before: loc)` becomes `query(heading.before(loc), loc)`. -/// Please refer to the [selector documentation]($type/selector) for more -/// details. +/// ## Command line queries { #command-line-queries } +/// You can also perform queries 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. Consider the following +/// `example.typ` file which contains some invisible [metadata]($func/metadata): +/// +/// ```typ +/// #metadata("This is a note") +/// ``` +/// +/// You can execute a query on it as follows using Typst's CLI: +/// ```sh +/// $ typst query example.typ "" +/// [ +/// { +/// "func": "metadata", +/// "value": "This is a note", +/// "label": "" +/// } +/// ] +/// ``` +/// +/// 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 "" --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 "" --field value --one +/// "This is a note" +/// ``` /// /// Display: Query /// Category: meta diff --git a/crates/typst-library/src/text/mod.rs b/crates/typst-library/src/text/mod.rs index ad705ca0d..9ab18ad96 100644 --- a/crates/typst-library/src/text/mod.rs +++ b/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, - /// 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, + /// 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, + /// The dominant direction for text and inline objects. Possible values are: /// /// - `{auto}`: Automatically infer the direction from the `lang` property. diff --git a/crates/typst-library/src/text/raw.rs b/crates/typst-library/src/text/raw.rs index 3d3fff408..b0abd369e 100644 --- a/crates/typst-library/src/text/raw.rs +++ b/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, - /// The theme to use for syntax highlighting. Theme files should be in the in the - /// `tmTheme` file format. + /// The theme to use for syntax highlighting. Theme files should be in the + /// 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 diff --git a/crates/typst-library/src/visualize/line.rs b/crates/typst-library/src/visualize/line.rs index b14e350bb..a476ffa70 100644 --- a/crates/typst-library/src/visualize/line.rs +++ b/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 - /// mentioned in the dictionary format above. For example, - /// `{(2pt + blue).thickness}` is `{2pt}`, `{(2pt + blue).miter-limit}` is - /// `{4.0}` (the default), and so on. + /// On a `stroke` object, you can access any of the fields mentioned in the + /// dictionary format above. For example, `{(2pt + blue).thickness}` is + /// `{2pt}`, `{(2pt + blue).miter-limit}` is `{4.0}` (the default), and so + /// on. /// /// ```example /// #set line(length: 100%) diff --git a/crates/typst-macros/src/element.rs b/crates/typst-macros/src/element.rs index 86a320bac..e047e6065 100644 --- a/crates/typst-macros/src/element.rs +++ b/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 } }; diff --git a/crates/typst-macros/src/func.rs b/crates/typst-macros/src/func.rs index a734d4047..77edff9a5 100644 --- a/crates/typst-macros/src/func.rs +++ b/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, diff --git a/crates/typst/src/eval/cast.rs b/crates/typst/src/eval/cast.rs index 6a49d1282..85cd02d48 100644 --- a/crates/typst/src/eval/cast.rs +++ b/crates/typst/src/eval/cast.rs @@ -281,13 +281,17 @@ impl Add for CastInfo { } } -/// A container for a variadic argument. -pub trait Variadics { +/// A container for an argument. +pub trait Container { /// The contained type. type Inner; } -impl Variadics for Vec { +impl Container for Option { + type Inner = T; +} + +impl Container for Vec { 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, - "closing" => MathClass::Closing, - "fence" => MathClass::Fence, - "large" => MathClass::Large, - "opening" => MathClass::Opening, + /// Punctuation, e.g. a comma. "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, } diff --git a/crates/typst/src/eval/mod.rs b/crates/typst/src/eval/mod.rs index 544f04f07..d79f2ea5f 100644 --- a/crates/typst/src/eval/mod.rs +++ b/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}; diff --git a/docs/reference/types.md b/docs/reference/types.md index 62c59cb00..429d41c27 100644 --- a/docs/reference/types.md +++ b/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 -(such as `5em + 2pt` instead of just `2pt`). Use the `abs` -field (such as in `(5em + 2pt).abs.pt()`) to ignore the -`em` component of the length (thus converting only its -absolute component). +Fails with an error if this length has non-zero `em` units (such as `5em + 2pt` +instead of just `2pt`). Use the `abs` field (such as in `(5em + 2pt).abs.pt()`) +to ignore the `em` component of the length (thus converting only its absolute +component). - returns: float ### mm() Converts this length to millimeters. -Fails with an error if this length has non-zero `em` units -(such as `5em + 2pt` instead of just `2pt`). See the -[`pt()`]($type/float.pt) method for more info. +Fails with an error if this length has non-zero `em` units (such as `5em + 2pt` +instead of just `2pt`). See the [`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 -(such as `5em + 2pt` instead of just `2pt`). See the -[`pt()`]($type/float.pt) method for more info. +Fails with an error if this length has non-zero `em` units (such as `5em + 2pt` +instead of just `2pt`). See the [`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 -(such as `5em + 2pt` instead of just `2pt`). See the -[`pt()`]($type/float.pt) method for more info. +Fails with an error if this length has non-zero `em` units (such as `5em + 2pt` +instead of just `2pt`). See the [`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 -array of [ratio]($type/ratio). Note that this function will throw an error when -applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not available. +Converts this color to Digital CMYK and returns its components (C, M, Y, K) as +an array of [ratios]($type/ratio). Note that this function will throw an error +when applied to an [rgb]($func/rgb) color, since its conversion to CMYK is not +available. - returns: array