diff --git a/library/src/basics/enum.rs b/library/src/basics/enum.rs index c5d4d8aef..2bff7133e 100644 --- a/library/src/basics/enum.rs +++ b/library/src/basics/enum.rs @@ -9,20 +9,8 @@ use crate::prelude::*; /// /// Displays a sequence of items vertically and numbers them consecutively. /// -/// ## Syntax -/// This functions also has dedicated syntax: -/// -/// - Starting a line with a plus sign creates an automatically numbered -/// enumeration item. -/// - Start a line with a number followed by a dot creates an explicitly -/// 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. -/// /// ## Example -/// ``` +/// ```example /// Automatically numbered: /// + Preparations /// + Analysis @@ -37,15 +25,26 @@ use crate::prelude::*; /// #enum[First][Second] /// ``` /// +/// ## Syntax +/// This functions also has dedicated syntax: +/// +/// - Starting a line with a plus sign creates an automatically numbered +/// enumeration item. +/// - Start a line with a number followed by a dot creates an explicitly +/// 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. +/// /// ## Parameters -/// - items: Content (positional, variadic) +/// - items: `Content` (positional, variadic) /// The enumeration's children. /// /// When using the enum syntax, adjacent items are automatically collected /// into enumerations, even through constructs like for loops. /// -/// ### Example -/// ``` +/// ```example /// #for phase in ( /// "Launch", /// "Orbit", @@ -53,11 +52,10 @@ use crate::prelude::*; /// ) [+ #phase] /// ``` /// -/// - start: NonZeroUsize (named) +/// - start: `NonZeroUsize` (named) /// Which number to start the enumeration with. /// -/// ### Example -/// ``` +/// ```example /// #enum( /// start: 3, /// [Skipping], @@ -65,14 +63,13 @@ use crate::prelude::*; /// ) /// ``` /// -/// - tight: bool (named) +/// - tight: `bool` (named) /// If this is `{false}`, the items are spaced apart with -/// [enum spacing](@enum/spacing). If it is `{true}`, they use normal -/// [leading](@par/leading) instead. This makes the enumeration more compact, -/// which can look better if the items are short. +/// [enum spacing]($func/enum.spacing). If it is `{true}`, they use normal +/// [leading]($func/par.leading) instead. This makes the enumeration more +/// compact, which can look better if the items are short. /// -/// ### Example -/// ``` +/// ```example /// + If an enum has a lot of text, and /// maybe other inline content, it /// should not be tight anymore. @@ -97,10 +94,9 @@ pub struct EnumNode { #[node] impl EnumNode { /// How to number the enumeration. Accepts a - /// [numbering pattern or function](@numbering). + /// [numbering pattern or function]($func/numbering). /// - /// # Example - /// ``` + /// ```example /// #set enum(numbering: "(a)") /// /// + Different @@ -121,7 +117,7 @@ impl EnumNode { /// The spacing between the items of a wide (non-tight) enumeration. /// - /// If set to `{auto}` uses the spacing [below blocks](@block/below). + /// If set to `{auto}` uses the spacing [below blocks]($func/block.below). pub const SPACING: Smart = Smart::Auto; fn construct(_: &Vm, args: &mut Args) -> SourceResult { diff --git a/library/src/basics/heading.rs b/library/src/basics/heading.rs index c2696dd6e..7ae76920b 100644 --- a/library/src/basics/heading.rs +++ b/library/src/basics/heading.rs @@ -16,14 +16,15 @@ use crate::text::{SpaceNode, TextNode, TextSize}; /// /// Typst can automatically number your headings for you. To enable numbering, /// specify how you want your headings to be numbered with a -/// [numbering pattern or function](@numbering). +/// [numbering pattern or function]($func/numbering). /// /// Independently from the numbering, Typst can also automatically generate an -/// [outline](@outline) of all headings for you. To exclude one or more headings -/// from this outline, you can set the `outlined` parameter to `{false}`. +/// [outline]($func/outline) of all headings for you. To exclude one or more +/// headings from this outline, you can set the `outlined` parameter to +/// `{false}`. /// /// ## Example -/// ``` +/// ```example /// #set heading(numbering: "1.a)") /// /// = Introduction @@ -39,10 +40,10 @@ use crate::text::{SpaceNode, TextNode, TextSize}; /// signs determines the heading's logical nesting depth. /// /// ## Parameters -/// - title: Content (positional, required) +/// - title: `Content` (positional, required) /// The heading's title. /// -/// - level: NonZeroUsize (named) +/// - level: `NonZeroUsize` (named) /// The logical nesting depth of the heading, starting from one. /// /// ## Category @@ -61,10 +62,9 @@ pub struct HeadingNode { #[node] impl HeadingNode { /// How to number the heading. Accepts a - /// [numbering pattern or function](@numbering). + /// [numbering pattern or function]($func/numbering). /// - /// # Example - /// ``` + /// ```example /// #set heading(numbering: "1.a.") /// /// = A section @@ -76,8 +76,7 @@ impl HeadingNode { /// Whether the heading should appear in the outline. /// - /// # Example - /// ``` + /// ```example /// #outline() /// /// #heading[Normal] diff --git a/library/src/basics/list.rs b/library/src/basics/list.rs index 42cee4ed6..4b9fdafbb 100644 --- a/library/src/basics/list.rs +++ b/library/src/basics/list.rs @@ -8,14 +8,8 @@ use crate::text::TextNode; /// Displays a sequence of items vertically, with each item introduced by a /// marker. /// -/// ## Syntax -/// 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. -/// /// ## Example -/// ``` +/// ```example /// - *Content* /// - Basics /// - Text @@ -34,28 +28,32 @@ use crate::text::TextNode; /// ) /// ``` /// +/// ## Syntax +/// 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. +/// /// ## Parameters -/// - items: Content (positional, variadic) +/// - items: `Content` (positional, variadic) /// The list's children. /// /// When using the list syntax, adjacent items are automatically collected /// into lists, even through constructs like for loops. /// -/// ### Example -/// ``` +/// ```example /// #for letter in "ABC" [ /// - Letter #letter /// ] /// ``` /// -/// - tight: bool (named) -/// If this is `{false}`, the items are spaced apart with -/// [list spacing](@list/spacing). If it is `{true}`, they use normal -/// [leading](@par/leading) instead. This makes the list more compact, which -/// can look better if the items are short. +/// - tight: `bool` (named) +/// If this is `{false}`, the items are spaced apart with [list +/// spacing]($func/list.spacing). If it is `{true}`, they use normal +/// [leading]($func/par.leading) instead. This makes the list more compact, +/// which can look better if the items are short. /// -/// ### Example -/// ``` +/// ```example /// - If a list has a lot of text, and /// maybe other inline content, it /// should not be tight anymore. @@ -80,8 +78,7 @@ pub struct ListNode { impl ListNode { /// The marker which introduces each element. /// - /// # Example - /// ``` + /// ```example /// #set list(marker: [--]) /// /// - A more classic list @@ -100,7 +97,7 @@ impl ListNode { /// The spacing between the items of a wide (non-tight) list. /// - /// If set to `{auto}` uses the spacing [below blocks](@block/below). + /// If set to `{auto}` uses the spacing [below blocks]($func/block.below). pub const SPACING: Smart = Smart::Auto; fn construct(_: &Vm, args: &mut Args) -> SourceResult { diff --git a/library/src/basics/table.rs b/library/src/basics/table.rs index 6ee2b0b26..56df2ceaa 100644 --- a/library/src/basics/table.rs +++ b/library/src/basics/table.rs @@ -7,11 +7,11 @@ use crate::prelude::*; /// Tables are used to arrange content in cells. Cells can contain arbitrary /// content, including multiple paragraphs and are specified in row-major order. /// Because tables are just grids with configurable cell properties, refer to -/// the [grid documentation](@grid) for more information on how to size the +/// the [grid documentation]($func/grid) for more information on how to size the /// table tracks. /// /// ## Example -/// ``` +/// ```example /// #table( /// columns: (1fr, auto, auto), /// inset: 10pt, @@ -31,28 +31,30 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - cells: Content (positional, variadic) +/// - cells: `Content` (positional, variadic) /// The contents of the table cells. /// -/// - rows: TrackSizings (named) +/// - rows: `TrackSizings` (named) /// Defines the row sizes. -/// See the [grid documentation](@grid) for more information on track sizing. +/// See the [grid documentation]($func/grid) for more information on track +/// sizing. /// -/// - columns: TrackSizings (named) +/// - columns: `TrackSizings` (named) /// Defines the column sizes. -/// See the [grid documentation](@grid) for more information on track sizing. +/// See the [grid documentation]($func/grid) for more information on track +/// sizing. /// -/// - gutter: TrackSizings (named) +/// - gutter: `TrackSizings` (named) /// Defines the gaps between rows & columns. -/// See the [grid documentation](@grid) for more information on gutters. +/// See the [grid documentation]($func/grid) for more information on gutters. /// -/// - column-gutter: TrackSizings (named) +/// - column-gutter: `TrackSizings` (named) /// Defines the gaps between columns. Takes precedence over `gutter`. -/// See the [grid documentation](@grid) for more information on gutters. +/// See the [grid documentation]($func/grid) for more information on gutters. /// -/// - row-gutter: TrackSizings (named) +/// - row-gutter: `TrackSizings` (named) /// Defines the gaps between rows. Takes precedence over `gutter`. -/// See the [grid documentation](@grid) for more information on gutters. +/// See the [grid documentation]($func/grid) for more information on gutters. /// /// ## Category /// basics @@ -76,8 +78,7 @@ impl TableNode { /// passed the cell's column and row index, starting at zero. This can be /// used to implement striped tables. /// - /// # Example - /// ``` + /// ```example /// #table( /// fill: (col, _) => if calc.odd(col) { luma(240) } else { white }, /// align: (col, row) => diff --git a/library/src/basics/terms.rs b/library/src/basics/terms.rs index 1409350a9..2e52c87dc 100644 --- a/library/src/basics/terms.rs +++ b/library/src/basics/terms.rs @@ -14,21 +14,20 @@ use crate::text::{SpaceNode, TextNode}; /// followed by a term, a colon and a description creates a term list item. /// /// ## Example -/// ``` +/// ```example /// / Ligature: A merged glyph. /// / Kerning: A spacing adjustment /// between two adjacent letters. /// ``` /// /// ## Parameters -/// - items: Content (positional, variadic) +/// - items: `Content` (positional, variadic) /// The term list's children. /// /// When using the term list syntax, adjacent items are automatically /// collected into term lists, even through constructs like for loops. /// -/// ### Example -/// ``` +/// ```example /// #for year, product in ( /// "1978": "TeX", /// "1984": "LaTeX", @@ -36,14 +35,13 @@ use crate::text::{SpaceNode, TextNode}; /// ) [/ #product: Born in #year.] /// ``` /// -/// - tight: bool (named) +/// - tight: `bool` (named) /// If this is `{false}`, the items are spaced apart with [term list -/// spacing](@terms/spacing). If it is `{true}`, they use normal -/// [leading](@par/leading) instead. This makes the term list more compact, -/// which can look better if the items are short. +/// spacing]($func/terms.spacing). If it is `{true}`, they use normal +/// [leading]($func/par.leading) instead. This makes the term list more +/// compact, which can look better if the items are short. /// -/// ### Example -/// ``` +/// ```example /// / Fact: If a term list has a lot /// of text, and maybe other inline /// content, it should not be tight @@ -74,8 +72,7 @@ impl TermsNode { /// The hanging indent of the description. /// - /// # Example - /// ``` + /// ```example /// #set terms(hanging-indent: 0pt) /// / Term: This term list does not /// make use of hanging indents. @@ -85,7 +82,7 @@ impl TermsNode { /// The spacing between the items of a wide (non-tight) term list. /// - /// If set to `{auto}` uses the spacing [below blocks](@block/below). + /// If set to `{auto}` uses the spacing [below blocks]($func/block.below). pub const SPACING: Smart = Smart::Auto; fn construct(_: &Vm, args: &mut Args) -> SourceResult { diff --git a/library/src/compute/calc.rs b/library/src/compute/calc.rs index 6ce1b1aef..8eae11852 100644 --- a/library/src/compute/calc.rs +++ b/library/src/compute/calc.rs @@ -41,14 +41,14 @@ pub fn calc() -> Module { /// Calculate the absolute value of a numeric value. /// /// ## Example -/// ``` +/// ```example /// #calc.abs(-5) \ /// #calc.abs(5pt - 2cm) \ /// #calc.abs(2fr) /// ``` /// /// ## Parameters -/// - value: ToAbs (positional, required) +/// - value: `ToAbs` (positional, required) /// The value whose absolute value to calculate. /// /// ## Category @@ -76,14 +76,14 @@ castable! { /// Raise a value to some exponent. /// /// ## Example -/// ``` +/// ```example /// #calc.pow(2, 3) /// ``` /// /// ## Parameters -/// - base: Num (positional, required) +/// - base: `Num` (positional, required) /// The base of the power. -/// - exponent: Num (positional, required) +/// - exponent: `Num` (positional, required) /// The exponent of the power. Must be non-negative. /// /// ## Category @@ -107,13 +107,13 @@ pub fn pow(args: &mut Args) -> SourceResult { /// Calculate the square root of a number. /// /// ## Example -/// ``` +/// ```example /// #calc.sqrt(16) \ /// #calc.sqrt(2.5) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number whose square root to calculate. Must be non-negative. /// /// ## Category @@ -134,14 +134,14 @@ pub fn sqrt(args: &mut Args) -> SourceResult { /// radians. /// /// ## Example -/// ``` +/// ```example /// #assert(calc.sin(90deg) == calc.sin(-270deg)) /// #calc.sin(1.5) \ /// #calc.sin(90deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose sine to calculate. /// /// ## Category @@ -163,14 +163,14 @@ pub fn sin(args: &mut Args) -> SourceResult { /// radians. /// /// ## Example -/// ``` +/// ```example /// #calc.cos(90deg) /// #calc.cos(1.5) \ /// #calc.cos(90deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose cosine to calculate. /// /// ## Category @@ -192,13 +192,13 @@ pub fn cos(args: &mut Args) -> SourceResult { /// radians. /// /// ## Example -/// ``` +/// ```example /// #calc.tan(1.5) \ /// #calc.tan(90deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose tangent to calculate. /// /// ## Category @@ -217,13 +217,13 @@ pub fn tan(args: &mut Args) -> SourceResult { /// Calculate the arcsine of a number. /// /// ## Example -/// ``` +/// ```example /// #calc.asin(0) \ /// #calc.asin(1) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number whose arcsine to calculate. Must be between -1 and 1. /// /// ## Category @@ -242,13 +242,13 @@ pub fn asin(args: &mut Args) -> SourceResult { /// Calculate the arccosine of a number. /// /// ## Example -/// ``` +/// ```example /// #calc.acos(0) \ /// #calc.acos(1) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number whose arccosine to calculate. Must be between -1 and 1. /// /// ## Category @@ -267,13 +267,13 @@ pub fn acos(args: &mut Args) -> SourceResult { /// Calculate the arctangent of a number. /// /// ## Example -/// ``` +/// ```example /// #calc.atan(0) \ /// #calc.atan(1) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number whose arctangent to calculate. /// /// ## Category @@ -290,13 +290,13 @@ pub fn atan(args: &mut Args) -> SourceResult { /// When called with an integer or a float, they will be interpreted as radians. /// /// ## Example -/// ``` +/// ```example /// #calc.sinh(0) \ /// #calc.sinh(45deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose hyperbolic sine to calculate. /// /// ## Category @@ -317,13 +317,13 @@ pub fn sinh(args: &mut Args) -> SourceResult { /// When called with an integer or a float, they will be interpreted as radians. /// /// ## Example -/// ``` +/// ```example /// #calc.cosh(0) \ /// #calc.cosh(45deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose hyperbolic cosine to calculate. /// /// ## Category @@ -344,13 +344,13 @@ pub fn cosh(args: &mut Args) -> SourceResult { /// When called with an integer or a float, they will be interpreted as radians. /// /// ## Example -/// ``` +/// ```example /// #calc.tanh(0) \ /// #calc.tanh(45deg) /// ``` /// /// ## Parameters -/// - angle: AngleLike (positional, required) +/// - angle: `AngleLike` (positional, required) /// The angle whose hyperbolic tangent to calculate. /// /// ## Category @@ -371,14 +371,14 @@ pub fn tanh(args: &mut Args) -> SourceResult { /// If the base is not specified, the logarithm is calculated in base 10. /// /// ## Example -/// ``` +/// ```example /// #calc.log(100) \ /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number whose logarithm to calculate. -/// - base: Num (named) +/// - base: `Num` (named) /// The base of the logarithm. /// /// ## Category @@ -396,14 +396,14 @@ pub fn log(args: &mut Args) -> SourceResult { /// If the number is already an integer, it is returned unchanged. /// /// ## Example -/// ``` +/// ```example /// #assert(calc.floor(3.14) == 3) /// #assert(calc.floor(3) == 3) /// #calc.floor(500.1) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number to round down. /// /// ## Category @@ -423,14 +423,14 @@ pub fn floor(args: &mut Args) -> SourceResult { /// If the number is already an integer, it is returned unchanged. /// /// ## Example -/// ``` +/// ```example /// #assert(calc.ceil(3.14) == 4) /// #assert(calc.ceil(3) == 3) /// #calc.ceil(500.1) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number to round up. /// /// ## Category @@ -450,16 +450,16 @@ pub fn ceil(args: &mut Args) -> SourceResult { /// Optionally, a number of decimal places can be specified. /// /// ## Example -/// ``` +/// ```example /// #assert(calc.round(3.14) == 3) /// #assert(calc.round(3.5) == 4) /// #calc.round(3.1415, digits: 2) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number to round. -/// - digits: i64 (named) +/// - digits: `i64` (named) /// /// ## Category /// calculate @@ -481,18 +481,18 @@ pub fn round(args: &mut Args) -> SourceResult { /// Clamp a number between a minimum and maximum value. /// /// ## Example -/// ``` +/// ```example /// #assert(calc.clamp(5, 0, 10) == 5) /// #assert(calc.clamp(5, 6, 10) == 6) /// #calc.clamp(5, 0, 4) /// ``` /// /// ## Parameters -/// - value: Num (positional, required) +/// - value: `Num` (positional, required) /// The number to clamp. -/// - min: Num (positional, required) +/// - min: `Num` (positional, required) /// The inclusive minimum value. -/// - max: Num (positional, required) +/// - max: `Num` (positional, required) /// The inclusive maximum value. /// /// ## Category @@ -512,13 +512,13 @@ pub fn clamp(args: &mut Args) -> SourceResult { /// Determine the minimum of a sequence of values. /// /// ## Example -/// ``` +/// ```example /// #calc.min(1, -3, -5, 20, 3, 6) \ /// #calc.min("typst", "in", "beta") /// ``` /// /// ## Parameters -/// - values: Value (positional, variadic) +/// - values: `Value` (positional, variadic) /// The sequence of values from which to extract the minimum. /// Must not be empty. /// @@ -535,13 +535,13 @@ pub fn min(args: &mut Args) -> SourceResult { /// Determine the maximum of a sequence of values. /// /// ## Example -/// ``` +/// ```example /// #calc.max(1, -3, -5, 20, 3, 6) \ /// #calc.max("typst", "in", "beta") /// ``` /// /// ## Parameters -/// - values: Value (positional, variadic) +/// - values: `Value` (positional, variadic) /// The sequence of values from which to extract the maximum. /// Must not be empty. /// @@ -579,14 +579,14 @@ fn minmax(args: &mut Args, goal: Ordering) -> SourceResult { /// Determine whether an integer is even. /// /// ## Example -/// ``` +/// ```example /// #calc.even(4) \ /// #calc.even(5) \ /// #range(10).filter(calc.even) /// ``` /// /// ## Parameters -/// - value: i64 (positional, required) +/// - value: `i64` (positional, required) /// The number to check for evenness. /// /// - returns: boolean @@ -602,7 +602,7 @@ pub fn even(args: &mut Args) -> SourceResult { /// Determine whether an integer is odd. /// /// ## Example -/// ``` +/// ```example /// #calc.odd(4) \ /// #calc.odd(5) \ /// #range(10).filter(calc.odd) @@ -610,7 +610,7 @@ pub fn even(args: &mut Args) -> SourceResult { /// /// /// ## Parameters -/// - value: i64 (positional, required) +/// - value: `i64` (positional, required) /// The number to check for oddness. /// /// - returns: boolean @@ -626,16 +626,16 @@ pub fn odd(args: &mut Args) -> SourceResult { /// Calculate the modulus of two numbers. /// /// ## Example -/// ``` +/// ```example /// #calc.mod(20, 6) \ /// #calc.mod(1.75, 0.5) /// ``` /// /// ## Parameters -/// - dividend: Num (positional, required) +/// - dividend: `Num` (positional, required) /// The dividend of the modulus. /// -/// - divisor: Num (positional, required) +/// - divisor: `Num` (positional, required) /// The divisor of the modulus. /// /// - returns: integer or float diff --git a/library/src/compute/construct.rs b/library/src/compute/construct.rs index 176409dd7..2d450d5d2 100644 --- a/library/src/compute/construct.rs +++ b/library/src/compute/construct.rs @@ -12,7 +12,7 @@ use crate::prelude::*; /// - Strings are parsed in base 10. /// /// ## Example -/// ``` +/// ```example /// #int(false) \ /// #int(true) \ /// #int(2.7) \ @@ -20,7 +20,7 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - value: ToInt (positional, required) +/// - value: `ToInt` (positional, required) /// The value that should be converted to an integer. /// /// - returns: integer @@ -52,7 +52,7 @@ castable! { /// Exponential notation is supported. /// /// ## Example -/// ``` +/// ```example /// #float(false) \ /// #float(true) \ /// #float(4) \ @@ -61,7 +61,7 @@ castable! { /// ``` /// /// ## Parameters -/// - value: ToFloat (positional, required) +/// - value: `ToFloat` (positional, required) /// The value that should be converted to a float. /// /// - returns: float @@ -88,14 +88,14 @@ castable! { /// Create a grayscale color. /// /// ## Example -/// ``` +/// ```example /// #for x in range(250, step: 50) { /// square(fill: luma(x)) /// } /// ``` /// /// ## Parameters -/// - gray: Component (positional, required) +/// - gray: `Component` (positional, required) /// The gray component. /// /// - returns: color @@ -118,14 +118,14 @@ pub fn luma(args: &mut Args) -> SourceResult { /// moment. This will be fixed in the future. /// /// ## Example -/// ``` +/// ```example /// #square(fill: rgb("#b1f2eb")) /// #square(fill: rgb(87, 127, 230)) /// #square(fill: rgb(25%, 13%, 65%)) /// ``` /// /// ## Parameters -/// - hex: EcoString (positional) +/// - hex: `EcoString` (positional) /// The color in hexadecimal notation. /// /// Accepts three, four, six or eight hexadecimal digits and optionally @@ -133,23 +133,22 @@ pub fn luma(args: &mut Args) -> SourceResult { /// /// If this string is given, the individual components should not be given. /// -/// ### Example -/// ``` +/// ```example /// #text(16pt, rgb("#239dad"))[ /// *Typst* /// ] /// ``` /// -/// - red: Component (positional) +/// - red: `Component` (positional) /// The red component. /// -/// - green: Component (positional) +/// - green: `Component` (positional) /// The green component. /// -/// - blue: Component (positional) +/// - blue: `Component` (positional) /// The blue component. /// -/// - alpha: Component (positional) +/// - alpha: `Component` (positional) /// The alpha component. /// /// - returns: color @@ -196,23 +195,23 @@ castable! { /// the color. /// /// ## Example -/// ``` +/// ```example /// #square( /// fill: cmyk(27%, 0%, 3%, 5%) /// ) /// ```` /// /// ## Parameters -/// - cyan: RatioComponent (positional, required) +/// - cyan: `RatioComponent` (positional, required) /// The cyan component. /// -/// - magenta: RatioComponent (positional, required) +/// - magenta: `RatioComponent` (positional, required) /// The magenta component. /// -/// - yellow: RatioComponent (positional, required) +/// - yellow: `RatioComponent` (positional, required) /// The yellow component. /// -/// - key: RatioComponent (positional, required) +/// - key: `RatioComponent` (positional, required) /// The key component. /// /// - returns: color @@ -244,7 +243,7 @@ castable! { /// Create a custom symbol with modifiers. /// /// ## Example -/// ``` +/// ```example /// #let envelope = symbol( /// "🖂", /// ("stamped", "🖃"), @@ -261,7 +260,7 @@ castable! { /// ``` /// /// ## Parameters -/// - variants: Variant (positional, variadic) +/// - variants: `Variant` (positional, variadic) /// The variants of the symbol. /// /// Can be a just a string consisting of a single character for the @@ -309,7 +308,7 @@ castable! { /// - From labels the name is extracted. /// /// ## Example -/// ``` +/// ```example /// #str(10) \ /// #str(2.7) \ /// #str(1e8) \ @@ -317,7 +316,7 @@ castable! { /// ``` /// /// ## Parameters -/// - value: ToStr (positional, required) +/// - value: `ToStr` (positional, required) /// The value that should be converted to a string. /// /// - returns: string @@ -344,11 +343,11 @@ castable! { /// Create a label from a string. /// /// Inserting a label into content attaches it to the closest previous element -/// that is not a space. Then, the element can be [referenced](@ref) and styled -/// through the label. +/// that is not a space. Then, the element can be [referenced]($func/ref) and +/// styled through the label. /// /// ## Example -/// ``` +/// ```example /// #show : set text(blue) /// #show label("b"): set text(red) /// @@ -361,7 +360,7 @@ castable! { /// its name in angle brackets. This works both in markup and code. /// /// ## Parameters -/// - name: EcoString (positional, required) +/// - name: `EcoString` (positional, required) /// The name of the label. /// /// - returns: label @@ -377,15 +376,14 @@ pub fn label(args: &mut Args) -> SourceResult { /// Create a regular expression from a string. /// /// The result can be used as a -/// [show rule selector](/docs/reference/styling/#show-rules) and with -/// [string methods](/docs/reference/types/string/#methods) like `find`, -/// `split`, and `replace`. +/// [show rule selector]($styling/#show-rules) and with +/// [string methods]($type/string) like `find`, `split`, and `replace`. /// /// [See here](https://docs.rs/regex/latest/regex/#syntax) for a specification /// of the supported syntax. /// /// ## Example -/// ``` +/// ```example /// // Works with show rules. /// #show regex("\d+"): set text(red) /// @@ -397,7 +395,7 @@ pub fn label(args: &mut Args) -> SourceResult { /// ``` /// /// ## Parameters -/// - regex: EcoString (positional, required) +/// - regex: `EcoString` (positional, required) /// The regular expression as a string. /// /// Most regex escape sequences just work because they are not valid Typst @@ -423,7 +421,7 @@ pub fn regex(args: &mut Args) -> SourceResult { /// range. /// /// ## Example -/// ``` +/// ```example /// #range(5) \ /// #range(2, 5) \ /// #range(20, step: 4) \ @@ -432,13 +430,13 @@ pub fn regex(args: &mut Args) -> SourceResult { /// ``` /// /// ## Parameters -/// - start: i64 (positional) +/// - start: `i64` (positional) /// The start of the range (inclusive). /// -/// - end: i64 (positional, required) +/// - end: `i64` (positional, required) /// The end of the range (exclusive). /// -/// - step: i64 (named) +/// - step: `i64` (named) /// The distance between the generated numbers. /// /// - returns: array diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs index 16b5fbbdc..305c66119 100644 --- a/library/src/compute/data.rs +++ b/library/src/compute/data.rs @@ -10,7 +10,7 @@ use crate::prelude::*; /// The file will be read and returned as a string. /// /// ## Example -/// ``` +/// ```example /// #let text = read("data.html") /// /// An example for a HTML file:\ @@ -18,7 +18,7 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - path: EcoString (positional, required) +/// - path: `EcoString` (positional, required) /// Path to a file. /// /// - returns: string @@ -47,7 +47,7 @@ pub fn read(vm: &Vm, args: &mut Args) -> SourceResult { /// stripped. /// /// ## Example -/// ``` +/// ```example /// #let results = csv("data.csv") /// /// #table( @@ -58,10 +58,10 @@ pub fn read(vm: &Vm, args: &mut Args) -> SourceResult { /// ``` /// /// ## Parameters -/// - path: EcoString (positional, required) +/// - path: `EcoString` (positional, required) /// Path to a CSV file. /// -/// - delimiter: Delimiter (named) +/// - delimiter: `Delimiter` (named) /// The delimiter that separates columns in the CSV file. /// Must be a single ASCII character. /// Defaults to a comma. @@ -149,7 +149,7 @@ fn format_csv_error(error: csv::Error) -> String { /// `unit`, and `weather`. /// /// ## Example -/// ``` +/// ```example /// #let forecast(day) = block[ /// #square( /// width: 2cm, @@ -174,7 +174,7 @@ fn format_csv_error(error: csv::Error) -> String { /// ``` /// /// ## Parameters -/// - path: EcoString (positional, required) +/// - path: `EcoString` (positional, required) /// Path to a JSON file. /// /// - returns: dictionary or array @@ -239,7 +239,7 @@ fn format_json_error(error: serde_json::Error) -> String { /// tags. /// /// ## Example -/// ``` +/// ```example /// #let findChild(elem, tag) = { /// elem.children /// .find(e => "tag" in e and e.tag == tag) @@ -273,7 +273,7 @@ fn format_json_error(error: serde_json::Error) -> String { /// ``` /// /// ## Parameters -/// - path: EcoString (positional, required) +/// - path: `EcoString` (positional, required) /// Path to an XML file. /// /// - returns: array diff --git a/library/src/compute/foundations.rs b/library/src/compute/foundations.rs index 2d5d84fe8..33a90ae42 100644 --- a/library/src/compute/foundations.rs +++ b/library/src/compute/foundations.rs @@ -10,7 +10,7 @@ use typst::syntax::Source; /// Returns the name of the value's type. /// /// ## Example -/// ``` +/// ```example /// #type(12) \ /// #type(14.7) \ /// #type("hello") \ @@ -20,7 +20,7 @@ use typst::syntax::Source; /// ``` /// /// ## Parameters -/// - value: Value (positional, required) +/// - value: `Value` (positional, required) /// The value whose type's to determine. /// /// - returns: string @@ -40,7 +40,7 @@ pub fn type_(args: &mut Args) -> SourceResult { /// integers, floats, strings, content, and functions. /// /// ## Example -/// ``` +/// ```example /// #none vs #repr(none) \ /// #"hello" vs #repr("hello") \ /// #(1, 2) vs #repr((1, 2)) \ @@ -48,7 +48,7 @@ pub fn type_(args: &mut Args) -> SourceResult { /// ``` /// /// ## Parameters -/// - value: Value (positional, required) +/// - value: `Value` (positional, required) /// The value whose string representation to produce. /// /// - returns: string @@ -67,12 +67,12 @@ pub fn repr(args: &mut Args) -> SourceResult { /// produce any output in the document. /// /// ## Example -/// ``` +/// ```example /// #assert(1 < 2) /// ``` /// /// ## Parameters -/// - condition: bool (positional, required) +/// - condition: `bool` (positional, required) /// The condition that must be true for the assertion to pass. /// /// ## Category @@ -97,13 +97,13 @@ pub fn assert(args: &mut Args) -> SourceResult { /// You shouldn't typically need this function, but it is there if you do. /// /// ## Example -/// ``` +/// ```example /// #let markup = "= Heading\n _Emphasis_" /// #eval(markup) /// ``` /// /// ## Parameters -/// - source: String (positional, required) +/// - source: `String` (positional, required) /// A string of Typst markup to evaluate. /// /// The markup and code in the string cannot interact with the file system. diff --git a/library/src/compute/utility.rs b/library/src/compute/utility.rs index 414a62f50..cb7655776 100644 --- a/library/src/compute/utility.rs +++ b/library/src/compute/utility.rs @@ -12,7 +12,7 @@ use crate::text::Case; /// sense. Use it as a placeholder to try layouts. /// /// ## Example -/// ``` +/// ```example /// = Blind Text /// #lorem(30) /// @@ -21,7 +21,7 @@ use crate::text::Case; /// ``` /// /// ## Parameters -/// - words: usize (positional, required) +/// - words: `usize` (positional, required) /// The length of the blind text in words. /// /// - returns: string @@ -41,12 +41,12 @@ pub fn lorem(args: &mut Args) -> SourceResult { /// content. It is defined either through a pattern string or an arbitrary /// function. /// -/// A numbering pattern consists of [counting symbols](#parameters--numbering) -/// for which the actual number is substituted, their prefixes, and one suffix. -/// The prefixes and the suffix are repeated as-is. +/// A numbering pattern consists of counting symbols, for which the actual +/// number is substituted, their prefixes, and one suffix. The prefixes and the +/// suffix are repeated as-is. /// /// ## Example -/// ``` +/// ```example /// #numbering("1.1)", 1, 2, 3) \ /// #numbering("1.a.i", 1, 2) \ /// #numbering("I – 1", 12, 2) \ @@ -60,7 +60,7 @@ pub fn lorem(args: &mut Args) -> SourceResult { /// ``` /// /// ## Parameters -/// - numbering: Numbering (positional, required) +/// - numbering: `Numbering` (positional, required) /// Defines how the numbering works. /// /// **Counting symbols** are `1`, `a`, `A`, `i`, `I` and `*`. They are @@ -84,7 +84,7 @@ pub fn lorem(args: &mut Args) -> SourceResult { /// numberings to the `numbering` function without caring whether they are /// defined as a pattern or function. /// -/// - numbers: NonZeroUsize (positional, variadic) +/// - numbers: `NonZeroUsize` (positional, variadic) /// The numbers to apply the numbering to. Must be positive. /// /// If `numbering` is a pattern and more numbers than counting symbols are diff --git a/library/src/layout/align.rs b/library/src/layout/align.rs index 35b1026ee..b84ccfdcb 100644 --- a/library/src/layout/align.rs +++ b/library/src/layout/align.rs @@ -4,7 +4,7 @@ use crate::prelude::*; /// Align content horizontally and vertically. /// /// ## Example -/// ``` +/// ```example /// #set align(center) /// /// Centered text, a sight to see \ @@ -14,10 +14,10 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to align. /// -/// - alignment: Axes> (positional, settable) +/// - alignment: `Axes>` (positional, settable) /// The alignment along both axes. /// /// Possible values for horizontal alignments are: @@ -28,7 +28,7 @@ use crate::prelude::*; /// - `right` /// /// The `start` and `end` alignments are relative to the current [text -/// direction](@text/dir). +/// direction]($func/text.dir). /// /// Possible values for vertical alignments are: /// - `top` @@ -39,8 +39,7 @@ use crate::prelude::*; /// the `+` operator to get a `2d alignment`. For example, `top + right` /// aligns the content to the top right corner. /// -/// ### Example -/// ``` +/// ```example /// #set page(height: 6cm) /// #set text(lang: "ar") /// diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs index 2b09bb692..55cda5d8c 100644 --- a/library/src/layout/columns.rs +++ b/library/src/layout/columns.rs @@ -11,7 +11,7 @@ use crate::text::TextNode; /// necessary. /// /// ## Example -/// ``` +/// ```example /// = Towards Advanced Deep Learning /// /// #box(height: 68pt, @@ -32,10 +32,10 @@ use crate::text::TextNode; /// ``` /// /// ## Parameters -/// - count: usize (positional, required) +/// - count: `usize` (positional, required) /// The number of columns. /// -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content that should be layouted into the columns. /// /// ## Category @@ -151,12 +151,12 @@ impl Layout for ColumnsNode { /// # Column Break /// A forced column break. /// -/// The function will behave like a [page break](@pagebreak) when used in a +/// The function will behave like a [page break]($func/pagebreak) when used in a /// single column layout or the last column on a page. Otherwise, content after /// the column break will be placed in the next column. /// /// ## Example -/// ``` +/// ```example /// #set page(columns: 2) /// Preliminary findings from our /// ongoing research project have @@ -174,7 +174,7 @@ impl Layout for ColumnsNode { /// ``` /// /// ## Parameters -/// - weak: bool (named) +/// - weak: `bool` (named) /// If `{true}`, the column break is skipped if the current column is already /// empty. /// diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs index afbce576b..094ed05a3 100644 --- a/library/src/layout/container.rs +++ b/library/src/layout/container.rs @@ -11,11 +11,12 @@ use crate::prelude::*; /// explicitly. /// /// _Note:_ While the behavior above will be the default in the future, the -/// transformation functions [`scale`](@scale), [`rotate`](@rotate), and -/// [`move`](@move) will currently yield inline nodes within paragraphs. +/// transformation functions [`scale`]($func/scale), [`rotate`]($func/rotate), +/// and [`move`]($func/move) will currently yield inline nodes within +/// paragraphs. /// /// ## Example -/// ``` +/// ```example /// Refer to the docs /// #box( /// height: 9pt, @@ -25,13 +26,13 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The contents of the box. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The width of the box. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The height of the box. /// /// ## Category @@ -109,7 +110,7 @@ impl Inline for BoxNode {} /// block-level. This is especially useful when writing show rules. /// /// ## Example -/// ``` +/// ```example /// #[ /// #show heading: it => it.title /// = No block @@ -124,19 +125,19 @@ impl Inline for BoxNode {} /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The contents of the block. /// -/// - spacing: Spacing (named, settable) +/// - spacing: `Spacing` (named, settable) /// The spacing around this block. /// -/// - above: Spacing (named, settable) +/// - above: `Spacing` (named, settable) /// The spacing between this block and its predecessor. Takes precedence over /// `spacing`. /// /// The default value is `{1.2em}`. /// -/// - below: Spacing (named, settable) +/// - below: `Spacing` (named, settable) /// The spacing between this block and its successor. Takes precedence /// over `spacing`. /// diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs index a3ee5df7e..60a5e7482 100644 --- a/library/src/layout/grid.rs +++ b/library/src/layout/grid.rs @@ -35,7 +35,7 @@ use super::Spacing; /// `columns:` `{(auto, auto, auto)}`. /// /// ## Example -/// ``` +/// ```example /// #set text(10pt, weight: "bold") /// #let cell = rect.with( /// inset: 8pt, @@ -60,30 +60,30 @@ use super::Spacing; /// ``` /// /// ## Parameters -/// - cells: Content (positional, variadic) The contents of the table cells. +/// - cells: `Content` (positional, variadic) The contents of the table cells. /// /// The cells are populated in row-major order. /// -/// - rows: TrackSizings (named) Defines the row sizes. +/// - rows: `TrackSizings` (named) Defines the row sizes. /// /// If there are more cells than fit the defined rows, the last row is /// repeated until there are no more cells. /// -/// - columns: TrackSizings (named) Defines the column sizes. +/// - columns: `TrackSizings` (named) Defines the column sizes. /// /// Either specify a track size array or provide an integer to create a grid /// with that many `{auto}`-sized columns. Note that opposed to rows and /// gutters, providing a single track size will only ever create a single /// column. /// -/// - gutter: TrackSizings (named) Defines the gaps between rows & columns. +/// - gutter: `TrackSizings` (named) Defines the gaps between rows & columns. /// /// If there are more gutters than defined sizes, the last gutter is repeated. /// -/// - column-gutter: TrackSizings (named) Defines the gaps between columns. +/// - column-gutter: `TrackSizings` (named) Defines the gaps between columns. /// Takes precedence over `gutter`. /// -/// - row-gutter: TrackSizings (named) Defines the gaps between rows. Takes +/// - row-gutter: `TrackSizings` (named) Defines the gaps between rows. Takes /// precedence over `gutter`. /// /// ## Category diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs index 01ae48c5b..cedc24894 100644 --- a/library/src/layout/hide.rs +++ b/library/src/layout/hide.rs @@ -9,13 +9,13 @@ use crate::prelude::*; /// not included in the output. /// /// ## Example -/// ``` +/// ```example /// Hello Jane \ /// #hide[Hello] Joe /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to hide. /// /// ## Category diff --git a/library/src/layout/pad.rs b/library/src/layout/pad.rs index 5c10050c2..aeea430b6 100644 --- a/library/src/layout/pad.rs +++ b/library/src/layout/pad.rs @@ -8,7 +8,7 @@ use crate::prelude::*; /// positional argument. /// /// ## Example -/// ``` +/// ```example /// #set align(center) /// /// #pad(x: 16pt, image("typing.jpg")) @@ -17,28 +17,28 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to pad at the sides. /// -/// - left: Rel (named) +/// - left: `Rel` (named) /// The padding at the left side. /// -/// - right: Rel (named) +/// - right: `Rel` (named) /// The padding at the right side. /// -/// - top: Rel (named) +/// - top: `Rel` (named) /// The padding at the top side. /// -/// - bottom: Rel (named) +/// - bottom: `Rel` (named) /// The padding at the bottom side. /// -/// - x: Rel (named) +/// - x: `Rel` (named) /// The horizontal padding. Both `left` and `right` take precedence over this. /// -/// - y: Rel (named) +/// - y: `Rel` (named) /// The vertical padding. Both `top` and `bottom` take precedence over this. /// -/// - rest: Rel (named) +/// - rest: `Rel` (named) /// The padding for all sides. All other parameters take precedence over this. /// /// ## Category diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs index 4f5231def..3de126341 100644 --- a/library/src/layout/page.rs +++ b/library/src/layout/page.rs @@ -14,19 +14,19 @@ use crate::prelude::*; /// the pages will grow to fit their content on the respective axis. /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The contents of the page(s). /// /// Multiple pages will be created if the content does not fit on a single /// page. A new page with the page properties prior to the function invocation /// will be created after the body has been typeset. /// -/// - paper: Paper (positional, settable) +/// - paper: `Paper` (positional, settable) /// A standard paper size to set width and height. When this is not specified, /// Typst defaults to `{"a4"}` paper. /// /// ## Example -/// ``` +/// ```example /// >>> #set page(margin: auto) /// #set page("us-letter") /// @@ -44,8 +44,7 @@ pub struct PageNode(pub Content); impl PageNode { /// The width of the page. /// - /// # Example - /// ``` + /// ```example /// #set page( /// width: 3cm, /// margin: (x: 0cm), @@ -61,16 +60,15 @@ impl PageNode { /// The height of the page. /// /// If this is set to `{auto}`, page breaks can only be triggered manually - /// by inserting a [page break](@pagebreak). Most examples throughout this - /// documentation use `{auto}` for the height of the page to dynamically - /// grow and shrink to fit their content. + /// by inserting a [page break]($func/pagebreak). Most examples throughout + /// this documentation use `{auto}` for the height of the page to + /// dynamically grow and shrink to fit their content. #[property(resolve)] pub const HEIGHT: Smart = Smart::Custom(Paper::A4.height().into()); /// Whether the page is flipped into landscape orientation. /// - /// # Example - /// ``` + /// ```example /// #set page( /// "us-business-card", /// flipped: true, @@ -103,8 +101,7 @@ impl PageNode { /// - `rest`: The margins on all sides except those for which the /// dictionary explicitly sets a size. /// - /// # Example - /// ``` + /// ```example /// #set page( /// width: 3cm, /// height: 4cm, @@ -122,8 +119,7 @@ impl PageNode { /// How many columns the page has. /// - /// # Example - /// ``` + /// ```example /// #set page(columns: 2, height: 4.8cm) /// Climate change is one of the most /// pressing issues of our time, with @@ -144,8 +140,7 @@ impl PageNode { /// environmentally friendly and cost-effective to source pre-dyed pages and /// not set this property. /// - /// # Example - /// ``` + /// ```example /// #set page(fill: rgb("444352")) /// #set text(fill: rgb("fdfdfd")) /// *Dark mode enabled.* @@ -162,8 +157,7 @@ impl PageNode { /// the header. /// - `{none}`: The header will be empty. /// - /// # Example - /// ``` + /// ```example /// #set par(justify: true) /// #set page( /// margin: (x: 24pt, y: 32pt), @@ -185,8 +179,7 @@ impl PageNode { /// the footer. /// - `{none}`: The footer will be empty. /// - /// # Example - /// ``` + /// ```example /// #set par(justify: true) /// #set page( /// margin: (x: 24pt, y: 32pt), @@ -205,8 +198,7 @@ impl PageNode { /// This content will be placed behind the page's body. It can be /// used to place a background image or a watermark. /// - /// # Example - /// ``` + /// ```example /// #set page(background: align( /// center + horizon, /// rotate(24deg, @@ -226,8 +218,7 @@ impl PageNode { /// /// This content will overlay the page's body. /// - /// # Example - /// ``` + /// ```example /// #set page(foreground: align( /// center + horizon, /// text(24pt)[🥸], @@ -355,7 +346,7 @@ impl Debug for PageNode { /// A manually forced page break. It must not be used inside any containers. /// /// ## Example -/// ``` +/// ```example /// The next page contains /// more details on compound theory. /// #pagebreak() @@ -366,7 +357,7 @@ impl Debug for PageNode { /// ``` /// /// ## Parameters -/// - weak: bool (named) +/// - weak: `bool` (named) /// If `{true}`, the page break is skipped if the current page is already empty. /// /// ## Category diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs index 2427aa98b..a629853a6 100644 --- a/library/src/layout/par.rs +++ b/library/src/layout/par.rs @@ -19,7 +19,7 @@ use crate::text::{ /// paragraph of its own. /// /// ## Example -/// ``` +/// ```example /// #set par(indent: 1em, justify: true) /// #show par: set block(spacing: 0.65em) /// @@ -36,7 +36,7 @@ use crate::text::{ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The contents of the paragraph. /// /// ## Category @@ -54,8 +54,8 @@ impl ParNode { /// /// By typographic convention, paragraph breaks are indicated by either some /// space between paragraphs or indented first lines. Consider turning the - /// [paragraph spacing](@block/spacing) off when using this property (e.g. - /// using `[#show par: set block(spacing: 0pt)]`). + /// [paragraph spacing]($func/block.spacing) off when using this property + /// (e.g. using `[#show par: set block(spacing: 0pt)]`). #[property(resolve)] pub const INDENT: Length = Length::zero(); @@ -68,12 +68,12 @@ impl ParNode { /// Whether to justify text in its line. /// /// Hyphenation will be enabled for justified paragraphs if the [text - /// property hyphenate](@text/hyphenate) is set to `{auto}` and the current - /// language is known. + /// property hyphenate]($func/text.hyphenate) is set to `{auto}` and the + /// current language is known. /// - /// Note that the current [alignment](@align) still has an effect on the - /// placement of the last line except if it ends with a [justified line - /// break](@linebreak/justify). + /// Note that the current [alignment]($func/align) still has an effect on + /// the placement of the last line except if it ends with a [justified line + /// break]($func/linebreak.justify). pub const JUSTIFY: bool = false; /// How to determine line breaks. @@ -83,8 +83,7 @@ impl ParNode { /// breaks for ragged paragraphs may also be worthwhile to improve the /// appearance of the text. /// - /// # Example - /// ``` + /// ```example /// #set page(width: 190pt) /// #set par(linebreaks: "simple") /// Some texts are frustratingly @@ -219,15 +218,11 @@ castable! { /// A paragraph break. /// /// This starts a new paragraph. Especially useful when used within code like -/// [for loops](/docs/reference/scripting/#loops). Multiple consecutive +/// [for loops]($scripting/#loops). Multiple consecutive /// paragraph breaks collapse into a single one. /// -/// ## Syntax -/// Instead of calling this function, you can insert a blank line into your -/// markup to create a paragraph break. -/// /// ## Example -/// ``` +/// ```example /// #for i in range(3) { /// [Blind text #i: ] /// lorem(5) @@ -235,6 +230,10 @@ castable! { /// } /// ``` /// +/// ## Syntax +/// Instead of calling this function, you can insert a blank line into your +/// markup to create a paragraph break. +/// /// ## Category /// layout #[func] diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs index c51c8289c..16b091fee 100644 --- a/library/src/layout/place.rs +++ b/library/src/layout/place.rs @@ -9,7 +9,7 @@ use crate::prelude::*; /// /// /// ## Example -/// ``` +/// ```example /// #set page(height: 60pt) /// Hello, world! /// @@ -23,21 +23,20 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - alignment: Axes> (positional) +/// - alignment: `Axes>` (positional) /// Relative to which position in the parent container to place the content. /// /// When an axis of the page is `{auto}` sized, all alignments relative to that /// axis will be ignored, instead, the item will be placed in the origin of the /// axis. /// -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to place. /// -/// - dx: Rel (named) +/// - dx: `Rel` (named) /// The horizontal displacement of the placed content. /// -/// ### Example -/// ``` +/// ```example /// #set align(center) /// /// #box( @@ -52,7 +51,7 @@ use crate::prelude::*; /// ) /// ``` /// -/// - dy: Rel (named) +/// - dy: `Rel` (named) /// The vertical displacement of the placed content. /// /// ## Category diff --git a/library/src/layout/repeat.rs b/library/src/layout/repeat.rs index df88bac56..06806fb07 100644 --- a/library/src/layout/repeat.rs +++ b/library/src/layout/repeat.rs @@ -9,7 +9,7 @@ use crate::prelude::*; /// sure to include negative space if you need the instances to overlap. /// /// ## Example -/// ``` +/// ```example /// Sign on the dotted line: #repeat[.] /// /// #set text(10pt) @@ -20,7 +20,7 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to repeat. /// /// ## Category diff --git a/library/src/layout/spacing.rs b/library/src/layout/spacing.rs index 640cd53a3..17f6b5bee 100644 --- a/library/src/layout/spacing.rs +++ b/library/src/layout/spacing.rs @@ -10,7 +10,7 @@ use crate::prelude::*; /// according to their relative fractions. /// /// ## Example -/// ``` +/// ```example /// #circle(fill: red) /// #h(1fr) /// #circle(fill: yellow) @@ -18,17 +18,20 @@ use crate::prelude::*; /// #circle(fill: green) /// ``` /// +/// ## Mathematical Spacing +/// In [mathematical formulas]($category/math), you can additionally use these +/// constants to add spacing between elements: `thin`, `med`, `thick, `quad`. +/// /// ## Parameters -/// - amount: Spacing (positional, required) +/// - amount: `Spacing` (positional, required) /// How much spacing to insert. /// -/// - weak: bool (named) +/// - weak: `bool` (named) /// If true, the spacing collapses at the start or end of a paragraph. /// Moreover, from multiple adjacent weak spacings all but the largest one /// collapse. /// -/// ### Example -/// ``` +/// ```example /// #h(1cm, weak: true) /// We identified a group of /// _weak_ specimens that fail to @@ -105,7 +108,7 @@ impl Behave for HNode { /// according to their relative fractions. /// /// ## Example -/// ``` +/// ```example /// In this report, we will explore /// the various ethical /// considerations that must be @@ -121,17 +124,16 @@ impl Behave for HNode { /// ``` /// /// ## Parameters -/// - amount: Spacing (positional, required) +/// - amount: `Spacing` (positional, required) /// How much spacing to insert. /// -/// - weak: bool (named) +/// - weak: `bool` (named) /// If true, the spacing collapses at the start or end of a flow. Moreover, /// from multiple adjacent weak spacings all but the largest one collapse. /// Weak spacings will always collapse adjacent paragraph spacing, even if the /// paragraph spacing is larger. /// -/// ### Example -/// ``` +/// ```example /// The following theorem is /// foundational to the field: /// #v(4pt, weak: true) diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs index 0fd0f2353..54b03bdc8 100644 --- a/library/src/layout/stack.rs +++ b/library/src/layout/stack.rs @@ -10,7 +10,7 @@ use crate::prelude::*; /// between each item. /// /// ## Example -/// ``` +/// ```example /// #stack( /// dir: ttb, /// rect(width: 40pt), @@ -20,10 +20,10 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - items: StackChild (positional, variadic) +/// - items: `StackChild` (positional, variadic) /// The items to stack along an axis. /// -/// - dir: Dir (named) +/// - dir: `Dir` (named) /// The direction along which the items are stacked. Possible values are: /// /// - `{ltr}`: Left to right. @@ -31,7 +31,7 @@ use crate::prelude::*; /// - `{ttb}`: Top to bottom. /// - `{btt}`: Bottom to top. /// -/// - spacing: Spacing (named) +/// - spacing: `Spacing` (named) /// Spacing to insert between items where no explicit spacing was provided. /// /// ## Category diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs index 09b4350d6..e3fd3250b 100644 --- a/library/src/layout/transform.rs +++ b/library/src/layout/transform.rs @@ -10,7 +10,7 @@ use crate::prelude::*; /// was not moved. /// /// ## Example -/// ``` +/// ```example /// #rect(inset: 0pt, move( /// dx: 6pt, dy: 6pt, /// rect( @@ -23,18 +23,17 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to move. /// -/// ### Example -/// ``` +/// ```example /// Hello, world!#move(dy: -2pt)[!]#move(dy: 2pt)[!] /// ``` /// -/// - dx: Rel (named) +/// - dx: `Rel` (named) /// The horizontal displacement of the content. /// -/// - dy: Rel (named) +/// - dy: `Rel` (named) /// The vertical displacement of the content. /// /// ## Category @@ -95,7 +94,7 @@ impl Inline for MoveNode {} /// was not rotated. /// /// ## Example -/// ``` +/// ```example /// #{ /// range(16) /// .map(i => rotate(24deg * i)[X]) @@ -104,14 +103,13 @@ impl Inline for MoveNode {} /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to rotate. /// -/// - angle: Angle (named) +/// - angle: `Angle` (named) /// The amount of rotation. /// -/// ### Example -/// ``` +/// ```example /// #rotate(angle: -1.571rad)[To space!] /// ``` /// @@ -136,8 +134,7 @@ impl RotateNode { /// stay aligned with the baseline, you would set the origin to `bottom + /// left`. /// - /// # Example - /// ``` + /// ```example /// #set text(spacing: 8pt) /// #let square = square.with(width: 8pt) /// @@ -195,21 +192,21 @@ impl Inline for RotateNode {} /// /// /// ## Example -/// ``` +/// ```example /// #set align(center) /// #scale(x: -100%)[👍]👩‍🦱👍 /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to scale. /// -/// - x: Ratio (named) +/// - x: `Ratio` (named) /// The horizontal scaling factor. /// /// The body will be mirrored horizontally if the parameter is negative. /// -/// - y: Ratio (named) +/// - y: `Ratio` (named) /// The vertical scaling factor. /// /// The body will be mirrored vertically if the parameter is negative. @@ -232,8 +229,7 @@ impl ScaleNode { /// /// By default, the origin is the center of the scaled element. /// - /// # Example - /// ``` + /// ```example /// A#scale(75%)[A]A \ /// B#scale(75%, origin: bottom + left)[B]B /// ``` diff --git a/library/src/math/accent.rs b/library/src/math/accent.rs index 223ada4f9..aa6d0523a 100644 --- a/library/src/math/accent.rs +++ b/library/src/math/accent.rs @@ -9,23 +9,22 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5); /// Attach an accent to a base. /// /// ## Example -/// ``` +/// ```example /// $grave(a) = accent(a, `)$ \ /// $arrow(a) = accent(a, arrow)$ \ /// $tilde(a) = accent(a, \u{0303})$ /// ``` /// /// ## Parameters -/// - base: Content (positional, required) +/// - base: `Content` (positional, required) /// The base to which the accent is applied. /// May consist of multiple letters. /// -/// ### Example -/// ``` +/// ```example /// $arrow(A B C)$ /// ``` /// -/// - accent: char (positional, required) +/// - accent: `char` (positional, required) /// The accent to apply to the base. /// /// Supported accents include: diff --git a/library/src/math/align.rs b/library/src/math/align.rs index e8a9c14a5..a9005dfd7 100644 --- a/library/src/math/align.rs +++ b/library/src/math/align.rs @@ -4,7 +4,7 @@ use super::*; /// A math alignment point: `&`, `&&`. /// /// ## Parameters -/// - index: usize (positional, required) +/// - index: `usize` (positional, required) /// The alignment point's index. /// /// ## Category diff --git a/library/src/math/attach.rs b/library/src/math/attach.rs index 7e6ac3882..31dc75ab0 100644 --- a/library/src/math/attach.rs +++ b/library/src/math/attach.rs @@ -8,18 +8,18 @@ use super::*; /// indicate a bottom attachment and the hat (`^`) to indicate a top attachment. /// /// ## Example -/// ``` +/// ```example /// $ sum_(i=0)^n a_i = 2^(1+i) $ /// ``` /// /// ## Parameters -/// - base: Content (positional, required) +/// - base: `Content` (positional, required) /// The base to which things are attached. /// -/// - top: Content (named) +/// - top: `Content` (named) /// The top attachment. /// -/// - bottom: Content (named) +/// - bottom: `Content` (named) /// The bottom attachment. /// /// ## Category @@ -84,12 +84,12 @@ impl LayoutMath for AttachNode { /// Force a base to display attachments as scripts. /// /// ## Example -/// ``` +/// ```example /// $ scripts(sum)_1^2 != sum_1^2 $ /// ``` /// /// ## Parameters -/// - base: Content (positional, required) +/// - base: `Content` (positional, required) /// The base to attach the scripts to. /// /// ## Category @@ -116,12 +116,12 @@ impl LayoutMath for ScriptsNode { /// Force a base to display attachments as limits. /// /// ## Example -/// ``` +/// ```example /// $ limits(A)_1^2 != A_1^2 $ /// ``` /// /// ## Parameters -/// - base: Content (positional, required) +/// - base: `Content` (positional, required) /// The base to attach the limits to. /// /// ## Category diff --git a/library/src/math/delimited.rs b/library/src/math/delimited.rs index 5b9decb6e..511f1a7be 100644 --- a/library/src/math/delimited.rs +++ b/library/src/math/delimited.rs @@ -10,16 +10,16 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1); /// unmatched delimiters and to control the delimiter scaling more precisely. /// /// ## Example -/// ``` +/// ```example /// $ lr(]a, b/2]) $ /// $ lr(]sum_(x=1)^n] x, size: #50%) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, variadic) +/// - body: `Content` (positional, variadic) /// The delimited content, including the delimiters. /// -/// - size: Rel (named) +/// - size: `Rel` (named) /// The size of the brackets, relative to the height of the wrapped content. /// /// Defaults to `{100%}`. @@ -120,12 +120,12 @@ fn scale( /// Floor an expression. /// /// ## Example -/// ``` +/// ```example /// $ floor(x/2) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The expression to floor. /// /// ## Category @@ -139,12 +139,12 @@ pub fn floor(args: &mut Args) -> SourceResult { /// Ceil an expression. /// /// ## Example -/// ``` +/// ```example /// $ ceil(x/2) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The expression to ceil. /// /// ## Category @@ -158,12 +158,12 @@ pub fn ceil(args: &mut Args) -> SourceResult { /// Take the absolute value of an expression. /// /// ## Example -/// ``` +/// ```example /// $ abs(x/2) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The expression to take the absolute value of. /// /// ## Category @@ -177,12 +177,12 @@ pub fn abs(args: &mut Args) -> SourceResult { /// Take the norm of an expression. /// /// ## Example -/// ``` +/// ```example /// $ norm(x/2) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The expression to take the norm of. /// /// ## Category diff --git a/library/src/math/frac.rs b/library/src/math/frac.rs index 283686c8a..cdf533da2 100644 --- a/library/src/math/frac.rs +++ b/library/src/math/frac.rs @@ -5,23 +5,23 @@ const FRAC_AROUND: Em = Em::new(0.1); /// # Fraction /// A mathematical fraction. /// +/// ## Example +/// ```example +/// $ 1/2 < (x+1)/2 $ +/// $ ((x+1)) / 2 = frac(a, b) $ +/// ``` +/// /// ## Syntax /// This function also has dedicated syntax: Use a slash to turn neighbouring /// expressions into a fraction. Multiple atoms can be grouped into a single /// expression using round grouping parenthesis. Such parentheses are removed /// from the output, but you can nest multiple to force them. /// -/// ## Example -/// ``` -/// $ 1/2 < (x+1)/2 $ -/// $ ((x+1)) / 2 = frac(a, b) $ -/// ``` -/// /// ## Parameters -/// - num: Content (positional, required) +/// - num: `Content` (positional, required) /// The fraction's numerator. /// -/// - denom: Content (positional, required) +/// - denom: `Content` (positional, required) /// The fraction's denominator. /// /// ## Category @@ -55,15 +55,15 @@ impl LayoutMath for FracNode { /// A binomial expression. /// /// ## Example -/// ``` +/// ```example /// $ binom(n, k) $ /// ``` /// /// ## Parameters -/// - upper: Content (positional, required) +/// - upper: `Content` (positional, required) /// The binomial's upper index. /// -/// - lower: Content (positional, required) +/// - lower: `Content` (positional, required) /// The binomial's lower index. /// /// ## Category diff --git a/library/src/math/matrix.rs b/library/src/math/matrix.rs index c47f2d5ee..c7b944172 100644 --- a/library/src/math/matrix.rs +++ b/library/src/math/matrix.rs @@ -10,13 +10,13 @@ const VERTICAL_PADDING: Ratio = Ratio::new(0.1); /// Content in the vector's elements can be aligned with the `&` symbol. /// /// ## Example -/// ``` +/// ```example /// $ vec(a, b, c) dot vec(1, 2, 3) /// = a + 2b + 3c $ /// ``` /// /// ## Parameters -/// - elements: Content (positional, variadic) +/// - elements: `Content` (positional, variadic) /// The elements of the vector. /// /// ## Category @@ -30,8 +30,7 @@ pub struct VecNode(Vec); impl VecNode { /// The delimiter to use. /// - /// # Example - /// ``` + /// ```example /// #set math.vec(delim: "[") /// $ vec(1, 2) $ /// ``` @@ -62,7 +61,7 @@ impl LayoutMath for VecNode { /// Content in cells that are in the same row can be aligned with the `&` symbol. /// /// ## Example -/// ``` +/// ```example /// $ mat( /// 1, 2, ..., 10; /// 2, 2, ..., 10; @@ -72,11 +71,10 @@ impl LayoutMath for VecNode { /// ``` /// /// ## Parameters -/// - rows: Array (positional, variadic) +/// - rows: `Array` (positional, variadic) /// An array of arrays with the rows of the matrix. /// -/// ### Example -/// ``` +/// ```example /// #let data = ((1, 2, 3), (4, 5, 6)) /// #let matrix = math.mat(..data) /// $ v := matrix $ @@ -93,8 +91,7 @@ pub struct MatNode(Vec>); impl MatNode { /// The delimiter to use. /// - /// # Example - /// ``` + /// ```example /// #set math.mat(delim: "[") /// $ mat(1, 2; 3, 4) $ /// ``` @@ -140,7 +137,7 @@ impl LayoutMath for MatNode { /// Content across different branches can be aligned with the `&` symbol. /// /// ## Example -/// ``` +/// ```example /// $ f(x, y) := cases( /// 1 "if" (x dot y)/2 <= 0, /// 2 "if" x "is even", @@ -150,7 +147,7 @@ impl LayoutMath for MatNode { /// ``` /// /// ## Parameters -/// - branches: Content (positional, variadic) +/// - branches: `Content` (positional, variadic) /// The branches of the case distinction. /// /// ## Category diff --git a/library/src/math/mod.rs b/library/src/math/mod.rs index 5aeedf6f8..105940c73 100644 --- a/library/src/math/mod.rs +++ b/library/src/math/mod.rs @@ -112,7 +112,7 @@ pub fn module() -> Module { /// Can be displayed inline with text or as a separate block. /// /// ## Example -/// ``` +/// ```example /// #set text("Latin Modern Roman") /// /// Let $a$, $b$, and $c$ be the side @@ -129,13 +129,13 @@ pub fn module() -> Module { /// dollar signs to create a formula. Starting and ending the formula with at /// least one space lifts it into a separate block that is centered /// horizontally. For more details about math syntax, see the -/// [main math page](/docs/reference/math). +/// [main math page]($category/math). /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The contents of the formula. /// -/// - block: bool (named) +/// - block: `bool` (named) /// Whether the formula is displayed as a separate block. /// /// ## Category diff --git a/library/src/math/op.rs b/library/src/math/op.rs index 8cc007ead..4451477e6 100644 --- a/library/src/math/op.rs +++ b/library/src/math/op.rs @@ -5,10 +5,18 @@ use super::*; /// # Text Operator /// A text operator in a math formula. /// +/// ## Predefined Operators +/// Typst predefines the operators `arccos`, `arcsin`, `arctan`, `arg`, +/// `cos`, `cosh`, `cot`, `coth`, `csc`, `deg`, `det`, `dim`, `exp`, +/// `gcd`, `hom`, `mod`, `inf`, `ker`, `lg`, `lim`, `ln`, `log`, `max`, +/// `min`, `Pr`, `sec`, `sin`, `sinh`, `sup`, `tan`, `tanh`, `liminf`, +/// and `limsup`. +/// /// ## Parameters -/// - text: EcoString (positional, required) +/// - text: `EcoString` (positional, required) /// The operator's text. -/// - limits: bool (named) +/// +/// - limits: `bool` (named) /// Whether the operator should force attachments to display as limits. /// /// Defaults to `{false}`. diff --git a/library/src/math/root.rs b/library/src/math/root.rs index fa41167df..e40f56f04 100644 --- a/library/src/math/root.rs +++ b/library/src/math/root.rs @@ -4,12 +4,12 @@ use super::*; /// A square root. /// /// ## Example -/// ``` +/// ```example /// $ sqrt(x^2) = x = sqrt(x)^2 $ /// ``` /// /// ## Parameters -/// - radicand: Content (positional, required) +/// - radicand: `Content` (positional, required) /// The expression to take the square root of. /// /// ## Category @@ -36,15 +36,15 @@ impl LayoutMath for SqrtNode { /// A general root. /// /// ## Example -/// ``` +/// ```example /// $ root(3, x) $ /// ``` /// /// ## Parameters -/// - index: Content (positional, required) +/// - index: `Content` (positional, required) /// Which root of the radicand to take. /// -/// - radicand: Content (positional, required) +/// - radicand: `Content` (positional, required) /// The expression to take the root of. /// /// ## Category diff --git a/library/src/math/style.rs b/library/src/math/style.rs index 9e1f66992..9856a6b08 100644 --- a/library/src/math/style.rs +++ b/library/src/math/style.rs @@ -4,12 +4,12 @@ use super::*; /// Bold font style in math. /// /// ## Example -/// ``` +/// ```example /// $ bold(A) := B^+ $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -39,12 +39,12 @@ impl LayoutMath for BoldNode { /// Upright (non-italic) font style in math. /// /// ## Example -/// ``` +/// ```example /// $ upright(A) != A $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -76,7 +76,7 @@ impl LayoutMath for UprightNode { /// For roman letters and greek lowercase letters, this is already the default. /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -108,7 +108,7 @@ impl LayoutMath for ItalicNode { /// This is already the default. /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -138,12 +138,12 @@ impl LayoutMath for SerifNode { /// Sans-serif font style in math. /// /// ## Example -/// ``` +/// ```example /// $ sans(A B C) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -173,12 +173,12 @@ impl LayoutMath for SansNode { /// Calligraphic font style in math. /// /// ## Example -/// ``` +/// ```example /// Let $cal(P)$ be the set of ... /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -208,12 +208,12 @@ impl LayoutMath for CalNode { /// Fraktur font style in math. /// /// ## Example -/// ``` +/// ```example /// $ frak(P) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -243,12 +243,12 @@ impl LayoutMath for FrakNode { /// Monospace font style in math. /// /// ## Example -/// ``` +/// ```example /// $ mono(x + y = z) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The piece of formula to style. /// /// ## Category @@ -278,17 +278,18 @@ impl LayoutMath for MonoNode { /// Blackboard bold (double-struck) font style in math. /// /// For uppercase latin letters, blackboard bold is additionally available -/// through [symbols](/docs/reference/math/symbols) of the form `NN` and `RR`. +/// through [symbols]($category/symbols/sym) of the form `NN` and `RR`. /// /// ## Example -/// ``` +/// ```example /// $ bb(b) $ /// $ bb(N) = NN $ /// $ f: NN -> RR $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) The piece of formula to style. +/// - body: `Content` (positional, required) +/// The piece of formula to style. /// /// ## Category /// math diff --git a/library/src/math/underover.rs b/library/src/math/underover.rs index a1c27e595..4387de201 100644 --- a/library/src/math/underover.rs +++ b/library/src/math/underover.rs @@ -8,12 +8,12 @@ const BRACKET_GAP: Em = Em::new(0.25); /// A horizontal line under content. /// /// ## Example -/// ``` +/// ```example /// $ underline(1 + 2 + ... + 5) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content above the line. /// /// ## Category @@ -40,12 +40,12 @@ impl LayoutMath for UnderlineNode { /// A horizontal line over content. /// /// ## Example -/// ``` +/// ```example /// $ overline(1 + 2 + ... + 5) $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content below the line. /// /// ## Category @@ -72,15 +72,15 @@ impl LayoutMath for OverlineNode { /// A horizontal brace under content, with an optional annotation below. /// /// ## Example -/// ``` +/// ```example /// $ underbrace(1 + 2 + ... + 5, "numbers") $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content above the brace. /// -/// - annotation: Content (positional) +/// - annotation: `Content` (positional) /// The optional content below the brace. /// /// ## Category @@ -114,15 +114,15 @@ impl LayoutMath for UnderbraceNode { /// A horizontal brace over content, with an optional annotation above. /// /// ## Example -/// ``` +/// ```example /// $ overbrace(1 + 2 + ... + 5, "numbers") $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content below the brace. /// -/// - annotation: Content (positional) +/// - annotation: `Content` (positional) /// The optional content above the brace. /// /// ## Category @@ -156,15 +156,15 @@ impl LayoutMath for OverbraceNode { /// A horizontal bracket under content, with an optional annotation below. /// /// ## Example -/// ``` +/// ```example /// $ underbracket(1 + 2 + ... + 5, "numbers") $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content above the bracket. /// -/// - annotation: Content (positional) +/// - annotation: `Content` (positional) /// The optional content below the bracket. /// /// ## Category @@ -198,15 +198,15 @@ impl LayoutMath for UnderbracketNode { /// A horizontal bracket over content, with an optional annotation above. /// /// ## Example -/// ``` +/// ```example /// $ overbracket(1 + 2 + ... + 5, "numbers") $ /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content below the bracket. /// -/// - annotation: Content (positional) +/// - annotation: `Content` (positional) /// The optional content above the bracket. /// /// ## Category diff --git a/library/src/meta/link.rs b/library/src/meta/link.rs index ebb7a7e99..ed941cf3b 100644 --- a/library/src/meta/link.rs +++ b/library/src/meta/link.rs @@ -10,7 +10,7 @@ use crate::text::TextNode; /// a style of your choice with a show rule. /// /// ## Example -/// ``` +/// ```example /// #show link: underline /// /// https://example.com \ @@ -25,7 +25,7 @@ use crate::text::TextNode; /// `https://` is automatically turned into a link. /// /// ## Parameters -/// - dest: Destination (positional, required) +/// - dest: `Destination` (positional, required) /// The destination the link points to. /// /// - To link to web pages, `dest` should be a valid URL string. If the URL is @@ -38,15 +38,14 @@ use crate::text::TextNode; /// coordinates of type `length`. Pages are counted from one, and the /// coordinates are relative to the page's top left corner. /// -/// ### Example -/// ``` +/// ```example /// #link("mailto:hello@typst.app") \ /// #link((page: 1, x: 0pt, y: 0pt))[ /// Go to top /// ] /// ``` /// -/// - body: Content (positional) +/// - body: `Content` (positional) /// /// The content that should become a link. If `dest` is an URL string, the /// parameter can be omitted. In this case, the URL will be shown as the link. diff --git a/library/src/meta/outline.rs b/library/src/meta/outline.rs index 4b70666b6..8a8bc57c3 100644 --- a/library/src/meta/outline.rs +++ b/library/src/meta/outline.rs @@ -7,11 +7,11 @@ use crate::text::{LinebreakNode, SpaceNode, TextNode}; /// A section outline / table of contents. /// /// This function generates a list of all headings in the document, up to a -/// given depth. The [heading](@heading) numbering will be reproduced within the -/// outline. +/// given depth. The [heading]($func/heading) numbering will be reproduced +/// within the outline. /// /// ## Example -/// ``` +/// ```example /// #outline() /// /// = Introduction @@ -33,7 +33,7 @@ impl OutlineNode { /// The title of the outline. /// /// - When set to `{auto}`, an appropriate title for the [text - /// language](@text/lang) will be used. This is the default. + /// language]($func/text.lang) will be used. This is the default. /// - When set to `{none}`, the outline will not have a title. /// - A custom title can be set by passing content. #[property(referenced)] @@ -45,10 +45,9 @@ impl OutlineNode { /// Whether to indent the subheadings to align the start of their numbering /// with the title of their parents. This will only have an effect if a - /// [heading numbering](@heading/numbering) is set. + /// [heading numbering]($func/heading.numbering) is set. /// - /// # Example - /// ``` + /// ```example /// #set heading(numbering: "1.a.") /// /// #outline(indent: true) @@ -67,8 +66,7 @@ impl OutlineNode { /// number. Can be set to `none` to disable filling. The default is a /// single dot. /// - /// # Example - /// ``` + /// ```example /// #outline( /// fill: pad(x: -1.5pt)[―] /// ) diff --git a/library/src/meta/reference.rs b/library/src/meta/reference.rs index 2165ed972..465a20ade 100644 --- a/library/src/meta/reference.rs +++ b/library/src/meta/reference.rs @@ -17,7 +17,7 @@ use crate::text::TextNode; /// Introduction ]` can be referenced by typing `[@intro]`). /// /// ## Parameters -/// - target: Label (positional, required) +/// - target: `Label` (positional, required) /// The label that should be referenced. /// /// ## Category diff --git a/library/src/text/deco.rs b/library/src/text/deco.rs index 6f454573f..4043141bb 100644 --- a/library/src/text/deco.rs +++ b/library/src/text/deco.rs @@ -8,12 +8,12 @@ use crate::prelude::*; /// Underline text. /// /// ## Example -/// ``` +/// ```example /// This is #underline[important]. /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to underline. /// /// ## Category @@ -28,8 +28,7 @@ impl UnderlineNode { /// How to stroke the line. The text color and thickness are read from the /// font tables if `{auto}`. /// - /// # Example - /// ``` + /// ```example /// Take #underline( /// stroke: 1.5pt + red, /// offset: 2pt, @@ -42,8 +41,7 @@ impl UnderlineNode { /// Position of the line relative to the baseline, read from the font tables /// if `{auto}`. /// - /// # Example - /// ``` + /// ```example /// #underline(offset: 5pt)[ /// The Tale Of A Faraway Line I /// ] @@ -53,8 +51,7 @@ impl UnderlineNode { /// Amount that the line will be longer or shorter than its associated text. /// - /// # Example - /// ``` + /// ```example /// #align(center, /// underline(extent: 2pt)[Chapter 1] /// ) @@ -65,8 +62,7 @@ impl UnderlineNode { /// Whether the line skips sections in which it would collide with the /// glyphs. /// - /// # Example - /// ``` + /// ```example /// This #underline(evade: true)[is great]. /// This #underline(evade: false)[is less great]. /// ``` @@ -103,12 +99,12 @@ impl Show for UnderlineNode { /// Add a line over text. /// /// ## Example -/// ``` +/// ```example /// #overline[A line over text.] /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to add a line over. /// /// ## Category @@ -123,8 +119,7 @@ impl OverlineNode { /// How to stroke the line. The text color and thickness are read from the /// font tables if `{auto}`. /// - /// # Example - /// ``` + /// ```example /// #set text(fill: olive) /// #overline( /// stroke: green.darken(20%), @@ -138,8 +133,7 @@ impl OverlineNode { /// Position of the line relative to the baseline, read from the font tables /// if `{auto}`. /// - /// # Example - /// ``` + /// ```example /// #overline(offset: -1.2em)[ /// The Tale Of A Faraway Line II /// ] @@ -149,8 +143,7 @@ impl OverlineNode { /// Amount that the line will be longer or shorter than its associated text. /// - /// # Example - /// ``` + /// ```example /// #set overline(extent: 4pt) /// #set underline(extent: 4pt) /// #overline(underline[Typography Today]) @@ -161,8 +154,7 @@ impl OverlineNode { /// Whether the line skips sections in which it would collide with the /// glyphs. /// - /// # Example - /// ``` + /// ```example /// #overline( /// evade: false, /// offset: -7.5pt, @@ -204,12 +196,12 @@ impl Show for OverlineNode { /// Strike through text. /// /// ## Example -/// ``` +/// ```example /// This is #strike[not] relevant. /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to strike through. /// /// ## Category @@ -227,8 +219,7 @@ impl StrikeNode { /// _Note:_ Please don't use this for real redaction as you can still /// copy paste the text. /// - /// # Example - /// ``` + /// ```example /// This is #strike(stroke: 1.5pt + red)[very stricken through]. \ /// This is #strike(stroke: 10pt)[redacted]. /// ``` @@ -240,8 +231,7 @@ impl StrikeNode { /// /// This is useful if you are unhappy with the offset your font provides. /// - /// # Example - /// ``` + /// ```example /// #set text(family: "Inria Serif") /// This is #strike(offset: auto)[low-ish]. \ /// This is #strike(offset: -3.5pt)[on-top]. @@ -251,8 +241,7 @@ impl StrikeNode { /// Amount that the line will be longer or shorter than its associated text. /// - /// # Example - /// ``` + /// ```example /// This #strike(extent: -2pt)[skips] parts of the word. /// This #strike(extent: 2pt)[extends] beyond the word. /// ``` @@ -287,8 +276,6 @@ impl Show for StrikeNode { } /// Defines a line that is positioned over, under or on top of text. -/// -/// For more details, see [`DecoNode`]. #[derive(Debug, Clone, Eq, PartialEq, Hash)] pub struct Decoration { pub line: DecoLine, diff --git a/library/src/text/misc.rs b/library/src/text/misc.rs index 75194a863..2129059a1 100644 --- a/library/src/text/misc.rs +++ b/library/src/text/misc.rs @@ -34,7 +34,7 @@ impl Behave for SpaceNode { /// lines. /// /// ## Example -/// ``` +/// ```example /// *Date:* 26.12.2022 \ /// *Topic:* Infrastructure Test \ /// *Severity:* High \ @@ -46,14 +46,13 @@ impl Behave for SpaceNode { /// break. /// /// ## Parameters -/// - justify: bool (named) +/// - justify: `bool` (named) /// Whether to justify the line before the break. /// /// This is useful if you found a better line break opportunity in your /// justified text than Typst did. /// -/// ### Example -/// ``` +/// ```example /// #set par(justify: true) /// #let jb = linebreak(justify: true) /// @@ -98,7 +97,7 @@ impl Behave for LinebreakNode { /// Increases the current font weight by a given `delta`. /// /// ## Example -/// ``` +/// ```example /// This is *strong.* \ /// This is #strong[too.] \ /// @@ -113,7 +112,7 @@ impl Behave for LinebreakNode { /// function. /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to strongly emphasize. /// /// ## Category @@ -127,8 +126,7 @@ pub struct StrongNode(pub Content); impl StrongNode { /// The delta to apply on the font weight. /// - /// # Example - /// ``` + /// ```example /// #set strong(delta: 0) /// No *effect!* /// ``` @@ -172,13 +170,13 @@ impl Fold for Delta { /// # Emphasis /// Emphasizes content by setting it in italics. /// -/// - If the current [text style](@text/style) is `{"normal"}`, +/// - If the current [text style]($func/text.style) is `{"normal"}`, /// this turns it into `{"italic"}`. /// - If it is already `{"italic"}` or `{"oblique"}`, /// it turns it back to `{"normal"}`. /// /// ## Example -/// ``` +/// ```example /// This is _emphasized._ \ /// This is #emph[too.] /// @@ -195,7 +193,7 @@ impl Fold for Delta { /// boundaries. To emphasize part of a word, you have to use the function. /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The content to emphasize. /// /// ## Category @@ -241,14 +239,14 @@ impl Fold for Toggle { /// Convert text or content to lowercase. /// /// ## Example -/// ``` +/// ```example /// #lower("ABC") \ /// #lower[*My Text*] \ /// #lower[already low] /// ``` /// /// ## Parameters -/// - text: ToCase (positional, required) +/// - text: `ToCase` (positional, required) /// The text to convert to lowercase. /// /// ## Category @@ -262,14 +260,14 @@ pub fn lower(args: &mut Args) -> SourceResult { /// Convert text or content to uppercase. /// /// ## Example -/// ``` +/// ```example /// #upper("abc") \ /// #upper[*my text*] \ /// #upper[ALREADY HIGH] /// ``` /// /// ## Parameters -/// - text: ToCase (positional, required) +/// - text: `ToCase` (positional, required) /// The text to convert to uppercase. /// /// ## Category @@ -328,7 +326,7 @@ impl Case { /// smallcaps from normal letters, but this is not yet implemented. /// /// ## Example -/// ``` +/// ```example /// #set par(justify: true) /// #set text(family: "Noto Serif") /// #set heading(numbering: "I.") @@ -344,7 +342,7 @@ impl Case { /// ``` /// /// ## Parameters -/// - text: Content (positional, required) +/// - text: `Content` (positional, required) /// The text to display to small capitals. /// /// ## Category diff --git a/library/src/text/mod.rs b/library/src/text/mod.rs index 675876554..a87fba872 100644 --- a/library/src/text/mod.rs +++ b/library/src/text/mod.rs @@ -31,7 +31,7 @@ use crate::prelude::*; /// useful when passing text as an argument to another function. /// /// ## Example -/// ``` +/// ```example /// #set text(18pt) /// With a set rule. /// @@ -41,7 +41,7 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - family: EcoString (positional, variadic, settable) +/// - family: `EcoString` (positional, variadic, settable) /// A prioritized sequence of font families. /// /// When processing text, Typst tries all specified font families in order @@ -49,8 +49,7 @@ use crate::prelude::*; /// the font `Inria Serif` is preferred, but since it does not contain Arabic /// glyphs, the arabic text uses `Noto Sans Arabic` instead. /// -/// ### Example -/// ``` +/// ```example /// #set text( /// "Inria Serif", /// "Noto Sans Arabic", @@ -61,7 +60,7 @@ use crate::prelude::*; /// /// ``` /// -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// Content in which all text is styled according to the other arguments. /// /// ## Category @@ -94,8 +93,7 @@ impl TextNode { /// future, you will be able to instruct Typst to issue warnings so you know /// something is up. /// - /// # Example - /// ``` + /// ```example /// #set text(family: "Inria Serif") /// هذا عربي /// @@ -114,11 +112,10 @@ impl TextNode { /// italic and oblique style is rarely observable. /// /// If you want to emphasize your text, you should do so using the - /// [emph](@emph) function instead. This makes it easy to adapt the style - /// later if you change your mind about how to signify the emphasis. + /// [emph]($func/emph) function instead. This makes it easy to adapt the + /// style later if you change your mind about how to signify the emphasis. /// - /// # Example - /// ``` + /// ```example /// #text("IBM Plex Sans", style: "italic")[Italic] /// #text("DejaVu Sans", style: "oblique")[Oblique] /// ``` @@ -130,12 +127,11 @@ impl TextNode { /// that is closest in weight. /// /// If you want to strongly emphasize your text, you should do so using the - /// [strong](@strong) function instead. This makes it easy to adapt the + /// [strong]($func/strong) function instead. This makes it easy to adapt the /// style later if you change your mind about how to signify the strong /// emphasis. /// - /// # Example - /// ``` + /// ```example /// #text(weight: "light")[Light] \ /// #text(weight: "regular")[Regular] \ /// #text(weight: "medium")[Medium] \ @@ -148,8 +144,7 @@ impl TextNode { /// `{200%}`. When the desired weight is not available, Typst selects the /// font from the family that is closest in stretch. /// - /// # Example - /// ``` + /// ```example /// #text(stretch: 75%)[Condensed] \ /// #text(stretch: 100%)[Normal] /// ``` @@ -161,8 +156,7 @@ impl TextNode { /// You can also give the font size itself in `em` units. Then, it is /// relative to the previous font size. /// - /// # Example - /// ``` + /// ```example /// #set text(size: 20pt) /// very #text(1.5em)[big] text /// ``` @@ -171,8 +165,7 @@ impl TextNode { /// The glyph fill color. /// - /// # Example - /// ``` + /// ```example /// #set text(fill: red) /// This text is red. /// ``` @@ -181,8 +174,7 @@ impl TextNode { /// The amount of space that should be added between characters. /// - /// # Example - /// ``` + /// ```example /// #set text(tracking: 1.5pt) /// Distant text. /// ``` @@ -194,8 +186,7 @@ impl TextNode { /// Can be given as an absolute length, but also relative to the width of /// the space character in the font. /// - /// # Example - /// ``` + /// ```example /// #set text(spacing: 200%) /// Text with distant words. /// ``` @@ -204,8 +195,7 @@ impl TextNode { /// An amount to shift the text baseline by. /// - /// # Example - /// ``` + /// ```example /// A #text(baseline: 3pt)[lowered] /// word. /// ``` @@ -215,8 +205,7 @@ impl TextNode { /// Whether certain glyphs can hang over into the margin in justified text. /// This can make justification visually more pleasing. /// - /// # Example - /// ``` + /// ```example /// #set par(justify: true) /// In this particular text, the /// justification produces a hyphen @@ -238,8 +227,7 @@ impl TextNode { /// The top end of the conceptual frame around the text used for layout and /// positioning. This affects the size of containers that hold text. /// - /// # Example - /// ``` + /// ```example /// #set rect(inset: 0pt) /// #set text(size: 20pt) /// @@ -254,8 +242,7 @@ impl TextNode { /// The bottom end of the conceptual frame around the text used for layout /// and positioning. This affects the size of containers that hold text. /// - /// # Example - /// ``` + /// ```example /// #set rect(inset: 0pt) /// #set text(size: 20pt) /// @@ -273,12 +260,11 @@ impl TextNode { /// /// - The text processing pipeline can make more informed choices. /// - Hyphenation will use the correct patterns for the language. - /// - [Smart quotes](@smartquote) turns into the correct quotes for the + /// - [Smart quotes]($func/smartquote) turns into the correct quotes for the /// language. /// - And all other things which are language-aware. /// - /// # Example - /// ``` + /// ```example /// #set text(lang: "de") /// #outline() /// @@ -299,20 +285,20 @@ impl TextNode { /// - `{rtl}`: Layout text from right to left. /// /// When writing in right-to-left scripts like Arabic or Hebrew, you should - /// set the [text language](@text/lang) or direction. While individual runs - /// of text are automatically layouted in the correct direction, setting the - /// dominant direction gives the bidirectional reordering algorithm the - /// necessary information to correctly place punctuation and inline objects. - /// Furthermore, setting the direction affects the alignment values `start` - /// and `end`, which are equivalent to `left` and `right` in `ltr` text and - /// the other way around in `rtl` text. + /// set the [text language]($func/text.lang) or direction. While individual + /// runs of text are automatically layouted in the correct direction, + /// setting the dominant direction gives the bidirectional reordering + /// algorithm the necessary information to correctly place punctuation and + /// inline objects. Furthermore, setting the direction affects the alignment + /// values `start` and `end`, which are equivalent to `left` and `right` in + /// `ltr` text and the other way around in `rtl` text. /// /// If you set this to `rtl` and experience bugs or in some way bad looking - /// output, please do get in touch with us through the [contact - /// form](/contact) or our [Discord server](/docs/community/#discord)! + /// output, please do get in touch with us through the + /// [contact form](https://typst.app/contact) or our + /// [Discord server]($community/#discord)! /// - /// # Example - /// ``` + /// ```example /// #set text(dir: rtl) /// هذا عربي. /// ``` @@ -322,11 +308,10 @@ impl TextNode { /// Whether to hyphenate text to improve line breaking. When `{auto}`, text /// will be hyphenated if and only if justification is enabled. /// - /// Setting the [text language](@text/lang) ensures that the correct + /// Setting the [text language]($func/text.lang) ensures that the correct /// hyphenation patterns are used. /// - /// # Example - /// ``` + /// ```example /// #set par(justify: true) /// This text illustrates how /// enabling hyphenation can @@ -348,8 +333,7 @@ impl TextNode { /// more natural look. Setting this to `{false}` disables kerning by turning /// off the OpenType `kern` font feature. /// - /// # Example - /// ``` + /// ```example /// #set text(size: 25pt) /// Totally /// @@ -364,8 +348,7 @@ impl TextNode { /// Setting this to `{true}` switches to these by enabling the OpenType /// `salt` font feature. /// - /// # Example - /// ``` + /// ```example /// #set text(size: 20pt) /// 0, a, g, ß /// @@ -388,8 +371,7 @@ impl TextNode { /// these ligatures by turning off the OpenType `liga` and `clig` font /// features. /// - /// # Example - /// ``` + /// ```example /// #set text(size: 20pt) /// A fine ligature. /// @@ -409,8 +391,7 @@ impl TextNode { /// Which kind of numbers / figures to select. When set to `{auto}`, the /// default numbers for the font are used. /// - /// # Example - /// ``` + /// ```example /// #set text(20pt, "Noto Sans") /// #set text(number-type: "lining") /// Number 9. @@ -423,8 +404,7 @@ impl TextNode { /// The width of numbers / figures. When set to `{auto}`, the default /// numbers for the font are used. /// - /// # Example - /// ``` + /// ```example /// #set text(20pt, "Noto Sans") /// #set text(number-width: "proportional") /// A 12 B 34. \ @@ -439,8 +419,7 @@ impl TextNode { /// Whether to have a slash through the zero glyph. Setting this to `{true}` /// enables the OpenType `zero` font feature. /// - /// # Example - /// ``` + /// ```example /// 0, #text(slashed-zero: true)[0] /// ``` pub const SLASHED_ZERO: bool = false; @@ -448,8 +427,7 @@ impl TextNode { /// Whether to turns numbers into fractions. Setting this to `{true}` /// enables the OpenType `frac` font feature. /// - /// # Example - /// ``` + /// ```example /// 1/2 \ /// #text(fractions: true)[1/2] /// ``` @@ -462,8 +440,7 @@ impl TextNode { /// - If given a dictionary mapping to numbers, sets the features /// identified by the keys to the values. /// - /// # Example - /// ``` + /// ```example /// // Enable the `frac` feature manually. /// #set text(features: ("frac",)) /// 1/2 diff --git a/library/src/text/quotes.rs b/library/src/text/quotes.rs index fa376b68b..c0a7e11c4 100644 --- a/library/src/text/quotes.rs +++ b/library/src/text/quotes.rs @@ -6,14 +6,10 @@ use crate::prelude::*; /// A language-aware quote that reacts to its context. /// /// Automatically turns into an appropriate opening or closing quote based on -/// the active [text language](@text/lang). -/// -/// ## Syntax -/// This function also has dedicated syntax: The normal quote characters -/// (`'` and `"`). Typst automatically makes your quotes smart. +/// the active [text language]($func/text.lang). /// /// ## Example -/// ``` +/// ```example /// "This is in quotes." /// /// #set text(lang: "de") @@ -23,8 +19,12 @@ use crate::prelude::*; /// "C'est entre guillemets." /// ``` /// +/// ## Syntax +/// This function also has dedicated syntax: The normal quote characters +/// (`'` and `"`). Typst automatically makes your quotes smart. +/// /// ## Parameters -/// - double: bool (named) +/// - double: `bool` (named) /// Whether this should be a double quote. /// /// ## Category @@ -43,8 +43,7 @@ impl SmartQuoteNode { /// To disable smartness for a single quote, you can also escape it with a /// backslash. /// - /// # Example - /// ``` + /// ```example /// #set smartquote(enabled: false) /// /// These are "dumb" quotes. diff --git a/library/src/text/raw.rs b/library/src/text/raw.rs index 1051992a1..e87d82e90 100644 --- a/library/src/text/raw.rs +++ b/library/src/text/raw.rs @@ -23,7 +23,7 @@ use crate::prelude::*; /// escape sequences. /// /// ## Example -/// ```` +/// ````example /// Adding `rbx` to `rcx` gives /// the desired result. /// @@ -35,14 +35,13 @@ use crate::prelude::*; /// ```` /// /// ## Parameters -/// - text: EcoString (positional, required) +/// - text: `EcoString` (positional, required) /// The raw text. /// /// You can also use raw blocks creatively to create custom syntaxes for /// your automations. /// -/// ### Example -/// ```` +/// ````example /// // Parse numbers in raw blocks with the /// // `mydsl` tag and sum them up. /// #show raw.where(lang: "mydsl"): it => { @@ -58,11 +57,10 @@ use crate::prelude::*; /// ``` /// ```` /// -/// - block: bool (named) +/// - block: `bool` (named) /// Whether the raw text is displayed as a separate block. /// -/// ### Example -/// ```` +/// ````example /// // Display inline code in a small box /// // that retains the correct baseline. /// #show raw.where(block: false): rect.with( @@ -107,8 +105,7 @@ impl RawNode { /// `{"typ"}` and `{"typc"}` tags for Typst markup and Typst code, /// respectively. /// - /// # Example - /// ```` + /// ````example /// ```typ /// This is *Typst!* /// ``` diff --git a/library/src/text/shift.rs b/library/src/text/shift.rs index 81b3c115a..9713c0c7e 100644 --- a/library/src/text/shift.rs +++ b/library/src/text/shift.rs @@ -10,12 +10,12 @@ use crate::prelude::*; /// The text is rendered smaller and its baseline is lowered. /// /// ## Example -/// ``` +/// ```example /// Revenue#sub[yearly] /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The text to display in subscript. /// /// ## Category @@ -33,8 +33,7 @@ impl SubNode { /// codepoints. If that fails, it falls back to rendering lowered and shrunk /// normal letters. /// - /// # Example - /// ``` + /// ```example /// N#sub(typographic: true)[1] /// N#sub(typographic: false)[1] /// ``` @@ -91,12 +90,12 @@ impl Show for SubNode { /// The text is rendered smaller and its baseline is raised. /// /// ## Example -/// ``` +/// ```example /// 1#super[st] try! /// ``` /// /// ## Parameters -/// - body: Content (positional, required) +/// - body: `Content` (positional, required) /// The text to display in superscript. /// /// ## Category @@ -114,8 +113,7 @@ impl SuperNode { /// superscript codepoints. If that fails, it falls back to rendering /// raised and shrunk normal letters. /// - /// # Example - /// ``` + /// ```example /// N#super(typographic: true)[1] /// N#super(typographic: false)[1] /// ``` diff --git a/library/src/visualize/image.rs b/library/src/visualize/image.rs index 07308b78d..87b672878 100644 --- a/library/src/visualize/image.rs +++ b/library/src/visualize/image.rs @@ -10,7 +10,7 @@ use crate::prelude::*; /// Supported formats are PNG, JPEG, GIF and SVG. /// /// ## Example -/// ``` +/// ```example /// #align(center)[ /// #image("molecular.jpg", width: 80%) /// @@ -20,13 +20,13 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - path: EcoString (positional, required) +/// - path: `EcoString` (positional, required) /// Path to an image file. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The width of the image. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The height of the image. /// /// ## Category diff --git a/library/src/visualize/line.rs b/library/src/visualize/line.rs index 188778426..4b4867809 100644 --- a/library/src/visualize/line.rs +++ b/library/src/visualize/line.rs @@ -4,24 +4,24 @@ use crate::prelude::*; /// A line from one point to another. /// /// ## Example -/// ``` +/// ```example /// #set page(height: 100pt) /// #line(end: (50%, 50%)) /// ``` /// /// ## Parameters -/// - start: Axes> (named) +/// - start: `Axes>` (named) /// The start point of the line. /// Must be an array of exactly two relative lengths. /// -/// - end: Axes> (named) +/// - end: `Axes>` (named) /// The end point of the line. /// Must be an array of exactly two relative lengths. /// -/// - length: Rel (named) +/// - length: `Rel` (named) /// The line's length. Mutually exclusive with `end`. /// -/// - angle: Angle (named) +/// - angle: `Angle` (named) /// The angle at which the line points away from the origin. Mutually /// exclusive with `end`. /// @@ -48,8 +48,7 @@ impl LineNode { /// - A stroke combined from color and thickness using the `+` operator as /// in `{2pt + red}`. /// - /// # Example - /// ``` + /// ```example /// #line(length: 100%, stroke: 2pt + red) /// ``` #[property(resolve, fold)] diff --git a/library/src/visualize/shape.rs b/library/src/visualize/shape.rs index 2a733368b..e6cb55f50 100644 --- a/library/src/visualize/shape.rs +++ b/library/src/visualize/shape.rs @@ -6,7 +6,7 @@ use crate::prelude::*; /// A rectangle with optional content. /// /// ## Example -/// ``` +/// ```example /// // Without content. /// #rect(width: 35%, height: 30pt) /// @@ -18,16 +18,16 @@ use crate::prelude::*; /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The content to place into the rectangle. /// /// When this is omitted, the rectangle takes on a default size of at most /// `{45pt}` by `{30pt}`. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The rectangle's width, relative to its parent container. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The rectangle's height, relative to its parent container. /// /// ## Category @@ -44,8 +44,7 @@ impl RectNode { /// When setting a fill, the default stroke disappears. To create a /// rectangle with both fill and stroke, you have to configure both. /// - /// # Example - /// ``` + /// ```example /// #rect(fill: blue) /// ``` pub const FILL: Option = None; @@ -73,8 +72,7 @@ impl RectNode { /// - `rest`: The stroke on all sides except those for which the /// dictionary explicitly sets a size. /// - /// # Example - /// ``` + /// ```example /// #stack( /// dir: ltr, /// spacing: 1fr, @@ -104,8 +102,7 @@ impl RectNode { /// - `rest`: The radii for all corners except those for which the /// dictionary explicitly sets a size. /// - /// # Example - /// ``` + /// ```example /// #set rect(stroke: 4pt) /// #rect( /// radius: ( @@ -129,10 +126,9 @@ impl RectNode { /// The default value is `{5pt}`. /// /// _Note:_ When the rectangle contains text, its exact size depends on the - /// current [text edges](@text/top-edge). + /// current [text edges]($func/text.top-edge). /// - /// # Example - /// ``` + /// ```example /// A #rect(inset: 0pt)[tight] fit. /// ``` #[property(resolve, fold)] @@ -142,10 +138,10 @@ impl RectNode { /// /// This is, for instance, useful to prevent an inline rectangle from /// affecting line layout. For a generalized version of the example below, - /// see the documentation for the [raw text's block parameter](@raw/block). + /// see the documentation for the + /// [raw text's block parameter]($func/raw.block). /// - /// # Example - /// ``` + /// ```example /// This /// #rect( /// fill: luma(235), @@ -203,7 +199,7 @@ impl Inline for RectNode {} /// A square with optional content. /// /// ## Example -/// ``` +/// ```example /// // Without content. /// #square(size: 40pt) /// @@ -215,24 +211,24 @@ impl Inline for RectNode {} /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The content to place into the square. The square expands to fit this /// content, keeping the 1-1 aspect ratio. /// /// When this is omitted, the square takes on a default size of at most /// `{30pt}`. /// -/// - size: Length (named) +/// - size: `Length` (named) /// The square's side length. This is mutually exclusive with `width` and /// `height`. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The square's width. This is mutually exclusive with `size` and `height`. /// /// In contrast to `size`, this can be relative to the parent container's /// width. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The square's height. This is mutually exclusive with `size` and `width`. /// /// In contrast to `size`, this can be relative to the parent container's @@ -247,29 +243,29 @@ pub struct SquareNode(pub Option); #[node] impl SquareNode { - /// How to fill the square. See the [rectangle's documentation](@rect/fill) - /// for more details. + /// How to fill the square. See the + /// [rectangle's documentation]($func/rect.fill) for more details. pub const FILL: Option = None; /// How to stroke the square. See the [rectangle's - /// documentation](@rect/stroke) for more details. + /// documentation]($func/rect.stroke) for more details. #[property(resolve, fold)] pub const STROKE: Smart>>> = Smart::Auto; /// How much to round the square's corners. See the [rectangle's - /// documentation](@rect/radius) for more details. + /// documentation]($func/rect.radius) for more details. #[property(resolve, fold)] pub const RADIUS: Corners>> = Corners::splat(Rel::zero()); /// How much to pad the square's content. See the [rectangle's - /// documentation](@rect/inset) for more details. + /// documentation]($func/rect.inset) for more details. /// /// The default value is `{5pt}`. #[property(resolve, fold)] pub const INSET: Sides>> = Sides::splat(Abs::pt(5.0).into()); /// How much to expand the square's size without affecting the layout. See - /// the [rectangle's documentation](@rect/outset) for more details. + /// the [rectangle's documentation]($func/rect.outset) for more details. #[property(resolve, fold)] pub const OUTSET: Sides>> = Sides::splat(Rel::zero()); @@ -326,7 +322,7 @@ impl Inline for SquareNode {} /// An ellipse with optional content. /// /// ## Example -/// ``` +/// ```example /// // Without content. /// #ellipse(width: 35%, height: 30pt) /// @@ -339,16 +335,16 @@ impl Inline for SquareNode {} /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The content to place into the ellipse. /// /// When this is omitted, the ellipse takes on a default size of at most /// `{45pt}` by `{30pt}`. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The ellipse's width, relative to its parent container. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The ellipse's height, relative to its parent container. /// /// ## Category @@ -360,24 +356,24 @@ pub struct EllipseNode(pub Option); #[node] impl EllipseNode { - /// How to fill the ellipse. See the [rectangle's documentation](@rect/fill) - /// for more details. + /// How to fill the ellipse. See the + /// [rectangle's documentation]($func/rect.fill) for more details. pub const FILL: Option = None; /// How to stroke the ellipse. See the [rectangle's - /// documentation](@rect/stroke) for more details. + /// documentation]($func/rect.stroke) for more details. #[property(resolve, fold)] pub const STROKE: Smart> = Smart::Auto; /// How much to pad the ellipse's content. See the [rectangle's - /// documentation](@rect/inset) for more details. + /// documentation]($func/rect.inset) for more details. /// /// The default value is `{5pt}`. #[property(resolve, fold)] pub const INSET: Sides>> = Sides::splat(Abs::pt(5.0).into()); /// How much to expand the ellipse's size without affecting the layout. See - /// the [rectangle's documentation](@rect/outset) for more details. + /// the [rectangle's documentation]($func/rect.outset) for more details. #[property(resolve, fold)] pub const OUTSET: Sides>> = Sides::splat(Rel::zero()); @@ -426,7 +422,7 @@ impl Inline for EllipseNode {} /// A circle with optional content. /// /// ## Example -/// ``` +/// ```example /// // Without content. /// #circle(radius: 25pt) /// @@ -439,21 +435,21 @@ impl Inline for EllipseNode {} /// ``` /// /// ## Parameters -/// - body: Content (positional) +/// - body: `Content` (positional) /// The content to place into the circle. The circle expands to fit this /// content, keeping the 1-1 aspect ratio. /// -/// - radius: Length (named) +/// - radius: `Length` (named) /// The circle's radius. This is mutually exclusive with `width` and /// `height`. /// -/// - width: Rel (named) +/// - width: `Rel` (named) /// The circle's width. This is mutually exclusive with `radius` and `height`. /// /// In contrast to `size`, this can be relative to the parent container's /// width. /// -/// - height: Rel (named) +/// - height: `Rel` (named) /// The circle's height.This is mutually exclusive with `radius` and `width`. /// /// In contrast to `size`, this can be relative to the parent container's @@ -468,24 +464,24 @@ pub struct CircleNode(pub Option); #[node] impl CircleNode { - /// How to fill the circle. See the [rectangle's documentation](@rect/fill) - /// for more details. + /// How to fill the circle. See the + /// [rectangle's documentation]($func/rect.fill) for more details. pub const FILL: Option = None; /// How to stroke the circle. See the [rectangle's - /// documentation](@rect/stroke) for more details. + /// documentation]($func/rect.stroke) for more details. #[property(resolve, fold)] pub const STROKE: Smart> = Smart::Auto; /// How much to pad the circle's content. See the [rectangle's - /// documentation](@rect/inset) for more details. + /// documentation]($func/rect.inset) for more details. /// /// The default value is `{5pt}`. #[property(resolve, fold)] pub const INSET: Sides>> = Sides::splat(Abs::pt(5.0).into()); /// How much to expand the circle's size without affecting the layout. See - /// the [rectangle's documentation](@rect/outset) for more details. + /// the [rectangle's documentation]($func/rect.outset) for more details. #[property(resolve, fold)] pub const OUTSET: Sides>> = Sides::splat(Rel::zero()); diff --git a/macros/src/func.rs b/macros/src/func.rs index 3253455be..e97684044 100644 --- a/macros/src/func.rs +++ b/macros/src/func.rs @@ -16,16 +16,9 @@ pub fn func(item: syn::Item) -> Result { let display = display.trim(); let mut docs = docs[first.len()..].to_string(); - let example = example(&mut docs, 2); let (params, returns) = params(&mut docs)?; - let syntax = quote_option(section(&mut docs, "Syntax", 2)); let category = section(&mut docs, "Category", 2).expect("missing category"); - let example = quote_option(example); - let docs = docs.trim(); - if docs.contains("# ") { - bail!(item, "unrecognized heading"); - } let info = quote! { ::typst::model::FuncInfo { @@ -33,8 +26,6 @@ pub fn func(item: syn::Item) -> Result { display: #display, category: #category, docs: #docs, - example: #example, - syntax: #syntax, params: ::std::vec![#(#params),*], returns: ::std::vec![#(#returns),*] } @@ -108,17 +99,6 @@ pub fn section(docs: &mut String, title: &str, level: usize) -> Option { Some(section) } -/// Parse the example section. -pub fn example(docs: &mut String, level: usize) -> Option { - let section = section(docs, "Example", level)?; - let mut s = unscanny::Scanner::new(§ion); - let count = s.eat_while('`').len(); - let term = "`".repeat(count); - let text = s.eat_until(term.as_str()).trim(); - s.expect(term.as_str()); - Some(text.into()) -} - /// Parse the parameter section. fn params(docs: &mut String) -> Result<(Vec, Vec)> { let Some(section) = section(docs, "Parameters", 2) else { @@ -151,7 +131,9 @@ fn params(docs: &mut String) -> Result<(Vec, Vec)> { continue; } - let ty: syn::Type = syn::parse_str(s.eat_until(char::is_whitespace))?; + s.expect('`'); + let ty: syn::Type = syn::parse_str(s.eat_until('`'))?; + s.expect('`'); s.eat_whitespace(); s.expect('('); @@ -176,15 +158,13 @@ fn params(docs: &mut String) -> Result<(Vec, Vec)> { s.expect(')'); - let mut docs = dedent(s.eat_until("\n-").trim()); - let example = quote_option(example(&mut docs, 3)); + let docs = dedent(s.eat_until("\n-").trim()); let docs = docs.trim(); infos.push(quote! { ::typst::model::ParamInfo { name: #name, docs: #docs, - example: #example, cast: <#ty as ::typst::model::Cast< ::typst::syntax::Spanned<::typst::model::Value> >>::describe(), diff --git a/macros/src/lib.rs b/macros/src/lib.rs index e162745a0..cd0f99887 100644 --- a/macros/src/lib.rs +++ b/macros/src/lib.rs @@ -26,7 +26,7 @@ mod symbols; use proc_macro::TokenStream as BoundaryStream; use proc_macro2::{TokenStream, TokenTree}; -use quote::{quote, quote_spanned, ToTokens}; +use quote::{quote, quote_spanned}; use syn::{parse_quote, Ident, Result}; /// Implement `FuncType` for a type or function. @@ -105,11 +105,3 @@ fn dedent(text: &str) -> String { .collect::>() .join("\n") } - -/// Quote an optional value. -fn quote_option(option: Option) -> TokenStream { - match option { - Some(value) => quote! { Some(#value) }, - None => quote! { None }, - } -} diff --git a/macros/src/node.rs b/macros/src/node.rs index cffac1842..b551182f3 100644 --- a/macros/src/node.rs +++ b/macros/src/node.rs @@ -336,15 +336,13 @@ fn create_node_properties_func(node: &Node) -> syn::ImplItemMethod { let value_ty = &property.value_ty; let shorthand = matches!(property.shorthand, Some(Shorthand::Positional)); - let mut docs = documentation(&property.attrs); - let example = quote_option(super::func::example(&mut docs, 1)); + let docs = documentation(&property.attrs); let docs = docs.trim(); quote! { ::typst::model::ParamInfo { name: #name, docs: #docs, - example: #example, cast: <#value_ty as ::typst::model::Cast< ::typst::syntax::Spanned<::typst::model::Value> >>::describe(), diff --git a/src/geom/ratio.rs b/src/geom/ratio.rs index 5c58649d3..7be16ff8f 100644 --- a/src/geom/ratio.rs +++ b/src/geom/ratio.rs @@ -3,7 +3,7 @@ use super::*; /// A ratio of a whole. /// /// _Note_: `50%` is represented as `0.5` here, but stored as `50.0` in the -/// corresponding [literal](crate::syntax::ast::LitKind::Numeric). +/// corresponding [literal](crate::syntax::ast::Numeric). #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] pub struct Ratio(Scalar); diff --git a/src/ide/highlight.rs b/src/ide/highlight.rs index 53b56d7a1..c12cb87a8 100644 --- a/src/ide/highlight.rs +++ b/src/ide/highlight.rs @@ -1,6 +1,6 @@ use crate::syntax::{ast, LinkedNode, SyntaxKind, SyntaxNode}; -/// Syntax highlighting tag. +/// A syntax highlighting tag. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] pub enum Tag { /// A line or block comment. diff --git a/src/lib.rs b/src/lib.rs index 0dc42152a..1c3998640 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,22 +1,25 @@ //! The compiler for the _Typst_ markup language. //! //! # Steps -//! - **Parsing:** The compiler first transforms a plain string into an -//! [iterator of tokens][tokens]. This token stream is [parsed] into a [syntax -//! tree]. The tree itself is untyped, but the [AST] module provides a typed -//! layer over it. -//! - **Evaluation:** The next step is to [evaluate] the markup. This produces a -//! [module], consisting of a scope of values that were exported by the code -//! and [content], a hierarchical, styled representation of what was written -//! in the source file. The nodes of the content tree are well structured and +//! - **Parsing:** +//! The compiler first transforms a plain string into an iterator of [tokens]. +//! This token stream is [parsed] into a [syntax tree]. The tree itself is +//! untyped, but the [AST] module provides a typed layer over it. +//! - **Evaluation:** +//! The next step is to [evaluate] the markup. This produces a [module], +//! consisting of a scope of values that were exported by the code and +//! [content], a hierarchical, styled representation of what was written in +//! the source file. The nodes of the content tree are well structured and //! order-independent and thus much better suited for further processing than //! the raw markup. -//! - **Typesetting:** Next, the content is [typeset] into a [document] -//! containing one [frame] per page with elements and fixed positions. -//! - **Exporting:** These frames can finally be exported into an output format -//! (currently supported are [PDF] and [raster images]). +//! - **Typesetting:** +//! Next, the content is [typeset] into a [document] containing one [frame] +//! per page with elements and fixed positions. +//! - **Exporting:** +//! These frames can finally be exported into an output format (currently +//! supported are [PDF] and [raster images]). //! -//! [tokens]: syntax::Tokens +//! [tokens]: syntax::SyntaxKind //! [parsed]: syntax::parse //! [syntax tree]: syntax::SyntaxNode //! [AST]: syntax::ast diff --git a/src/model/func.rs b/src/model/func.rs index 1ccb01070..c5bab64c6 100644 --- a/src/model/func.rs +++ b/src/model/func.rs @@ -226,18 +226,14 @@ pub struct FuncInfo { pub name: &'static str, /// The display name of the function. pub display: &'static str, - /// Which category the function is part of. - pub category: &'static str, /// Documentation for the function. pub docs: &'static str, - /// The source code of an example, if any. - pub example: Option<&'static str>, - /// Documentation about this function's syntax, if it has syntax. - pub syntax: Option<&'static str>, /// Details about the function's parameters. pub params: Vec, /// Valid types for the return value. pub returns: Vec<&'static str>, + /// Which category the function is part of. + pub category: &'static str, } impl FuncInfo { @@ -254,8 +250,6 @@ pub struct ParamInfo { pub name: &'static str, /// Documentation for the parameter. pub docs: &'static str, - /// The source code of an example, if any. - pub example: Option<&'static str>, /// Valid values for the parameter. pub cast: CastInfo, /// Is the parameter positional? diff --git a/src/model/symbol.rs b/src/model/symbol.rs index 9d226801b..16ab58af9 100644 --- a/src/model/symbol.rs +++ b/src/model/symbol.rs @@ -6,7 +6,6 @@ use std::sync::Arc; use crate::diag::StrResult; use crate::util::EcoString; -/// Define a list of symbols. #[doc(inline)] pub use typst_macros::symbols; @@ -169,8 +168,6 @@ fn contained(modifiers: &str, m: &str) -> bool { } /// Normalize an accent to a combining one. -/// -/// https://www.w3.org/TR/mathml-core/#combining-character-equivalences pub fn combining_accent(c: char) -> Option { Some(match c { '\u{0300}' | '`' => '\u{0300}', diff --git a/src/util/mod.rs b/src/util/mod.rs index 0b6812237..b20dd0536 100644 --- a/src/util/mod.rs +++ b/src/util/mod.rs @@ -37,7 +37,7 @@ where } /// Calculate a 128-bit siphash of a value. -pub fn hash128(value: &T) -> u128 { +pub fn hash128(value: &T) -> u128 { let mut state = SipHasher::new(); value.hash(&mut state); state.finish128().as_u128()