konevsa/typst
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make Rust happier about the inline documentation

Browse Source
This commit is contained in:
Laurenz 2023-02-06 11:52:09 +01:00
parent 0bb0f1c98f
commit ea8edfa821
55 changed files with 582 additions and 690 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
library/src/basics/enum.rs
View File

@ -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<Spacing> = Smart::Auto;
fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

21
library/src/basics/heading.rs
View File

@ -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]

37
library/src/basics/list.rs
View File

@ -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<Spacing> = Smart::Auto;
fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

31
library/src/basics/table.rs
View File

@ -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) =>

23
library/src/basics/terms.rs
View File

@ -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<Spacing> = Smart::Auto;
fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {

100
library/src/compute/calc.rs
View File

@ -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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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<Value> {
///
///
/// ## 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<Value> {
/// 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

70
library/src/compute/construct.rs
View File

@ -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<Value> {
/// 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<Value> {
///
/// 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 <a>: 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<Value> {
/// 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<Value> {
/// ```
///
/// ## 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<Value> {
/// range.
///
/// ## Example
/// ```
/// ```example
/// #range(5) \
/// #range(2, 5) \
/// #range(20, step: 4) \
@ -432,13 +430,13 @@ pub fn regex(args: &mut Args) -> SourceResult<Value> {
/// ```
///
/// ## 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

18
library/src/compute/data.rs
View File

@ -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<Value> {
/// stripped.
///
/// ## Example
/// ```
/// ```example
/// #let results = csv("data.csv")
///
/// #table(
@ -58,10 +58,10 @@ pub fn read(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
/// ```
///
/// ## 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

16
library/src/compute/foundations.rs
View File

@ -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<Value> {
/// 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<Value> {
/// ```
///
/// ## 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<Value> {
/// 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<Value> {
/// 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.

16
library/src/compute/utility.rs
View File

@ -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<Value> {
/// 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<Value> {
/// ```
///
/// ## 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<Value> {
/// 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

11
library/src/layout/align.rs
View File

@ -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<Option<GenAlign>> (positional, settable)
/// - alignment: `Axes<Option<GenAlign>>` (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")
///

12
library/src/layout/columns.rs
View File

@ -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.
///

23
library/src/layout/container.rs
View File

@ -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<Length> (named)
/// - width: `Rel<Length>` (named)
/// The width of the box.
///
/// - height: Rel<Length> (named)
/// - height: `Rel<Length>` (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`.
///

14
library/src/layout/grid.rs
View File

@ -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

4
library/src/layout/hide.rs
View File

@ -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

18
library/src/layout/pad.rs
View File

@ -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<Length> (named)
/// - left: `Rel<Length>` (named)
/// The padding at the left side.
///
/// - right: Rel<Length> (named)
/// - right: `Rel<Length>` (named)
/// The padding at the right side.
///
/// - top: Rel<Length> (named)
/// - top: `Rel<Length>` (named)
/// The padding at the top side.
///
/// - bottom: Rel<Length> (named)
/// - bottom: `Rel<Length>` (named)
/// The padding at the bottom side.
///
/// - x: Rel<Length> (named)
/// - x: `Rel<Length>` (named)
/// The horizontal padding. Both `left` and `right` take precedence over this.
///
/// - y: Rel<Length> (named)
/// - y: `Rel<Length>` (named)
/// The vertical padding. Both `top` and `bottom` take precedence over this.
///
/// - rest: Rel<Length> (named)
/// - rest: `Rel<Length>` (named)
/// The padding for all sides. All other parameters take precedence over this.
///
/// ## Category

43
library/src/layout/page.rs
View File

@ -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<Length> = 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

33
library/src/layout/par.rs
View File

@ -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]

13
library/src/layout/place.rs
View File

@ -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<Option<GenAlign>> (positional)
/// - alignment: `Axes<Option<GenAlign>>` (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<Length> (named)
/// - dx: `Rel<Length>` (named)
/// The horizontal displacement of the placed content.
///
/// ### Example
/// ```
/// ```example
/// #set align(center)
///
/// #box(
@ -52,7 +51,7 @@ use crate::prelude::*;
/// )
/// ```
///
/// - dy: Rel<Length> (named)
/// - dy: `Rel<Length>` (named)
/// The vertical displacement of the placed content.
///
/// ## Category

4
library/src/layout/repeat.rs
View File

@ -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

22
library/src/layout/spacing.rs
View File

@ -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)

8
library/src/layout/stack.rs
View File

@ -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

34
library/src/layout/transform.rs
View File

@ -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<Length> (named)
/// - dx: `Rel<Length>` (named)
/// The horizontal displacement of the content.
///
/// - dy: Rel<Length> (named)
/// - dy: `Rel<Length>` (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
/// ```

9
library/src/math/accent.rs
View File

@ -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:

2
library/src/math/align.rs
View File

@ -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

16
library/src/math/attach.rs
View File

@ -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

22
library/src/math/delimited.rs
View File

@ -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<Length> (named)
/// - size: `Rel<Length>` (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<Value> {
/// 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<Value> {
/// 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<Value> {
/// 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

22
library/src/math/frac.rs
View File

@ -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

21
library/src/math/matrix.rs
View File

@ -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<Content>);
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<Vec<Content>>);
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

8
library/src/math/mod.rs
View File

@ -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

12
library/src/math/op.rs
View File

@ -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}`.

10
library/src/math/root.rs
View File

@ -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

35
library/src/math/style.rs
View File

@ -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

32
library/src/math/underover.rs
View File

@ -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

9
library/src/meta/link.rs
View File

@ -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.

16
library/src/meta/outline.rs
View File

@ -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)[―]
/// )

2
library/src/meta/reference.rs
View File

@ -17,7 +17,7 @@ use crate::text::TextNode;
/// Introduction <intro>]` can be referenced by typing `[@intro]`).
///
/// ## Parameters
/// - target: Label (positional, required)
/// - target: `Label` (positional, required)
/// The label that should be referenced.
///
/// ## Category

47
library/src/text/deco.rs
View File

@ -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,

32
library/src/text/misc.rs
View File

@ -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<Value> {
/// 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

107
library/src/text/mod.rs
View File

@ -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

17
library/src/text/quotes.rs
View File

@ -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.

15
library/src/text/raw.rs
View File

@ -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!*
/// ```

14
library/src/text/shift.rs
View File

@ -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]
/// ```

8
library/src/visualize/image.rs
View File

@ -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<Length> (named)
/// - width: `Rel<Length>` (named)
/// The width of the image.
///
/// - height: Rel<Length> (named)
/// - height: `Rel<Length>` (named)
/// The height of the image.
///
/// ## Category

13
library/src/visualize/line.rs
View File

@ -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<Rel<Length>> (named)
/// - start: `Axes<Rel<Length>>` (named)
/// The start point of the line.
/// Must be an array of exactly two relative lengths.
///
/// - end: Axes<Rel<Length>> (named)
/// - end: `Axes<Rel<Length>>` (named)
/// The end point of the line.
/// Must be an array of exactly two relative lengths.
///
/// - length: Rel<Length> (named)
/// - length: `Rel<Length>` (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)]

88
library/src/visualize/shape.rs
View File

@ -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<Length> (named)
/// - width: `Rel<Length>` (named)
/// The rectangle's width, relative to its parent container.
///
/// - height: Rel<Length> (named)
/// - height: `Rel<Length>` (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<Paint> = 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<Length> (named)
/// - width: `Rel<Length>` (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<Length> (named)
/// - height: `Rel<Length>` (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<Content>);
#[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<Paint> = 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<Sides<Option<Option<PartialStroke>>>> = 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<Option<Rel<Length>>> = 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<Option<Rel<Length>>> = 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<Option<Rel<Length>>> = 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<Length> (named)
/// - width: `Rel<Length>` (named)
/// The ellipse's width, relative to its parent container.
///
/// - height: Rel<Length> (named)
/// - height: `Rel<Length>` (named)
/// The ellipse's height, relative to its parent container.
///
/// ## Category
@ -360,24 +356,24 @@ pub struct EllipseNode(pub Option<Content>);
#[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<Paint> = 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<Option<PartialStroke>> = 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<Option<Rel<Length>>> = 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<Option<Rel<Length>>> = 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<Length> (named)
/// - width: `Rel<Length>` (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<Length> (named)
/// - height: `Rel<Length>` (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<Content>);
#[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<Paint> = 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<Option<PartialStroke>> = 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<Option<Rel<Length>>> = 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<Option<Rel<Length>>> = Sides::splat(Rel::zero());

28
macros/src/func.rs
View File

@ -16,16 +16,9 @@ pub fn func(item: syn::Item) -> Result<TokenStream> {
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<TokenStream> {
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<String> {
Some(section)
}
/// Parse the example section.
pub fn example(docs: &mut String, level: usize) -> Option<String> {
let section = section(docs, "Example", level)?;
let mut s = unscanny::Scanner::new(&section);
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<TokenStream>, Vec<String>)> {
let Some(section) = section(docs, "Parameters", 2) else {
@ -151,7 +131,9 @@ fn params(docs: &mut String) -> Result<(Vec<TokenStream>, Vec<String>)> {
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<TokenStream>, Vec<String>)> {
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(),

10
macros/src/lib.rs
View File

@ -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::<Vec<_>>()
.join("\n")
}
/// Quote an optional value.
fn quote_option<T: ToTokens>(option: Option<T>) -> TokenStream {
match option {
Some(value) => quote! { Some(#value) },
None => quote! { None },
}
}

4
macros/src/node.rs
View File

@ -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(),

2
src/geom/ratio.rs
View File

@ -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);

2
src/ide/highlight.rs
View File

@ -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.

29
src/lib.rs
View File

@ -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

10
src/model/func.rs
View File

@ -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<ParamInfo>,
/// 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?

3
src/model/symbol.rs
View File

@ -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<char> {
Some(match c {
'\u{0300}' | '`' => '\u{0300}',

2
src/util/mod.rs
View File

@ -37,7 +37,7 @@ where
}
/// Calculate a 128-bit siphash of a value.
pub fn hash128<T: Hash>(value: &T) -> u128 {
pub fn hash128<T: Hash + ?Sized>(value: &T) -> u128 {
let mut state = SipHasher::new();
value.hash(&mut state);
state.finish128().as_u128()