Docs and changelog improvements (#5147)

Co-authored-by: Malo <57839069+MDLC01@users.noreply.github.com>
Co-authored-by: Andrew Voynov <37143421+Andrew15-5@users.noreply.github.com>
Co-authored-by: PgBiel <9021226+PgBiel@users.noreply.github.com>
Co-authored-by: Jeremie Knuesel <knuesel@gmail.com>
Co-authored-by: +merlan #flirora <2975203+bluebear94@users.noreply.github.com>
Co-authored-by: Anselm Schüler <mail@anselmschueler.com>

README.md

@@ -129,7 +129,7 @@ Typst's CLI is available from different sources:
     `nix run github:typst/typst -- --version`.
 
 - Docker users can run a prebuilt image with
-  `docker run -it ghcr.io/typst/typst:latest`.
+  `docker run ghcr.io/typst/typst:latest --help`.
 
 ## Usage
 Once you have installed Typst, you can use it like this:

crates/typst-cli/src/args.rs

@@ -209,7 +209,9 @@ pub struct QueryCommand {
     #[clap(long = "format", default_value = "json")]
     pub format: SerializationFormat,
 
-    /// Whether to pretty-print the serialized output
+    /// Whether to pretty-print the serialized output.
+    ///
+    /// Only applies to JSON format.
     #[clap(long)]
     pub pretty: bool,
 }

crates/typst/src/foundations/array.rs

@@ -486,7 +486,8 @@ impl Array {
         /// function is a bit involved, so we parse the positional arguments manually).
         args: &mut Args,
         /// Whether all arrays have to have the same length.
-        /// For example, `(1, 2).zip((1, 2, 3), exact: true)` produces an error.
+        /// For example, `{(1, 2).zip((1, 2, 3), exact: true)}` produces an
+        /// error.
         #[named]
         #[default(false)]
         exact: bool,

crates/typst/src/foundations/calc.rs

@@ -92,7 +92,7 @@ cast! {
 /// Raises a value to some exponent.
 ///
 /// ```example
-/// #calc.pow(2, 3)
+/// #calc.pow(2, 3) \
 /// #calc.pow(decimal("2.5"), 2)
 /// ```
 #[func(title = "Power")]
@@ -236,7 +236,6 @@ pub fn root(
 /// radians.
 ///
 /// ```example
-/// #assert(calc.sin(90deg) == calc.sin(-270deg))
 /// #calc.sin(1.5) \
 /// #calc.sin(90deg)
 /// ```
@@ -258,7 +257,6 @@ pub fn sin(
 /// radians.
 ///
 /// ```example
-/// #calc.cos(90deg) \
 /// #calc.cos(1.5) \
 /// #calc.cos(90deg)
 /// ```
@@ -621,10 +619,10 @@ pub fn lcm(
 /// 64-bit signed integer or smaller than the minimum for that type.
 ///
 /// ```example
+/// #calc.floor(500.1)
 /// #assert(calc.floor(3) == 3)
 /// #assert(calc.floor(3.14) == 3)
 /// #assert(calc.floor(decimal("-3.14")) == -4)
-/// #calc.floor(500.1)
 /// ```
 #[func]
 pub fn floor(
@@ -648,10 +646,10 @@ pub fn floor(
 /// 64-bit signed integer or smaller than the minimum for that type.
 ///
 /// ```example
+/// #calc.ceil(500.1)
 /// #assert(calc.ceil(3) == 3)
 /// #assert(calc.ceil(3.14) == 4)
 /// #assert(calc.ceil(decimal("-3.14")) == -3)
-/// #calc.ceil(500.1)
 /// ```
 #[func]
 pub fn ceil(
@@ -675,10 +673,10 @@ pub fn ceil(
 /// 64-bit signed integer or smaller than the minimum for that type.
 ///
 /// ```example
+/// #calc.trunc(15.9)
 /// #assert(calc.trunc(3) == 3)
 /// #assert(calc.trunc(-3.7) == -3)
 /// #assert(calc.trunc(decimal("8493.12949582390")) == 8493)
-/// #calc.trunc(15.9)
 /// ```
 #[func(title = "Truncate")]
 pub fn trunc(
@@ -698,9 +696,9 @@ pub fn trunc(
 /// If the number is an integer, returns `0`.
 ///
 /// ```example
+/// #calc.fract(-3.1)
 /// #assert(calc.fract(3) == 0)
 /// #assert(calc.fract(decimal("234.23949211")) == decimal("0.23949211"))
-/// #calc.fract(-3.1)
 /// ```
 #[func(title = "Fractional")]
 pub fn fract(
@@ -734,6 +732,7 @@ pub fn fract(
 /// for maximum and minimum respectively.
 ///
 /// ```example
+/// #calc.round(3.1415, digits: 2)
 /// #assert(calc.round(3) == 3)
 /// #assert(calc.round(3.14) == 3)
 /// #assert(calc.round(3.5) == 4.0)
@@ -745,7 +744,6 @@ pub fn fract(
 /// #assert(calc.round(decimal("7.123456789"), digits: 6) == decimal("7.123457"))
 /// #assert(calc.round(decimal("3333.45"), digits: -2) == decimal("3300"))
 /// #assert(calc.round(decimal("-48953.45"), digits: -3) == decimal("-49000"))
-/// #calc.round(3.1415, digits: 2)
 /// ```
 #[func]
 pub fn round(
@@ -776,11 +774,11 @@ pub fn round(
 /// Clamps a number between a minimum and maximum value.
 ///
 /// ```example
+/// #calc.clamp(5, 0, 4)
 /// #assert(calc.clamp(5, 0, 10) == 5)
 /// #assert(calc.clamp(5, 6, 10) == 6)
 /// #assert(calc.clamp(decimal("5.45"), 2, decimal("45.9")) == decimal("5.45"))
 /// #assert(calc.clamp(decimal("5.45"), decimal("6.75"), 12) == decimal("6.75"))
-/// #calc.clamp(5, 0, 4)
 /// ```
 #[func]
 pub fn clamp(
@@ -991,7 +989,7 @@ pub fn div_euclid(
 /// #calc.rem-euclid(7, -3) \
 /// #calc.rem-euclid(-7, 3) \
 /// #calc.rem-euclid(-7, -3) \
-/// #calc.rem-euclid(1.75, 0.5)
+/// #calc.rem-euclid(1.75, 0.5) \
 /// #calc.rem-euclid(decimal("1.75"), decimal("0.5"))
 /// ```
 #[func(title = "Euclidean Remainder")]

crates/typst/src/foundations/decimal.rs

@@ -34,9 +34,10 @@ use crate::World;
 /// constructing a decimal from a [floating-point number]($float), while
 /// supported, **is an imprecise conversion and therefore discouraged.** A
 /// warning will be raised if Typst detects that there was an accidental `float`
-/// to `decimal` cast through its constructor (e.g. if writing `{decimal(3.14)}`
+/// to `decimal` cast through its constructor, e.g. if writing `{decimal(3.14)}`
-/// - note the lack of double quotes, indicating this is an accidental `float`
+/// (note the lack of double quotes, indicating this is an accidental `float`
-/// cast and therefore imprecise).
+/// cast and therefore imprecise). It is recommended to use strings for
+/// constant decimal values instead (e.g. `{decimal("3.14")}`).
 ///
 /// The precision of a `float` to `decimal` cast can be slightly improved by
 /// rounding the result to 15 digits with [`calc.round`]($calc.round), but there
@@ -81,11 +82,11 @@ use crate::World;
 /// multiplication, and [power]($calc.pow) to an integer, will be highly precise
 /// due to their fixed-point representation. Note, however, that multiplication
 /// and division may not preserve all digits in some edge cases: while they are
-/// considered precise, digits past the limits specified below are rounded off
+/// considered precise, digits past the limits specified above are rounded off
 /// and lost, so some loss of precision beyond the maximum representable digits
 /// is possible. Note that this behavior can be observed not only when dividing,
 /// but also when multiplying by numbers between 0 and 1, as both operations can
-/// push a number's fractional digits beyond the limits described below, leading
+/// push a number's fractional digits beyond the limits described above, leading
 /// to rounding. When those two operations do not surpass the digit limits, they
 /// are fully precise.
 #[ty(scope, cast)]
@@ -287,7 +288,7 @@ impl Decimal {
     /// writing `{decimal(1.234)}` (note the lack of double quotes), which is
     /// why Typst will emit a warning in that case. Please write
     /// `{decimal("1.234")}` instead for that particular case (initialization of
-    /// a constant decimal). Also note that floats equal to NaN and infinity
+    /// a constant decimal). Also note that floats that are NaN or infinite
     /// cannot be cast to decimals and will raise an error.
     ///
     /// ```example
@@ -296,6 +297,7 @@ impl Decimal {
     #[func(constructor)]
     pub fn construct(
         engine: &mut Engine,
+        /// The value that should be converted to a decimal.
         value: Spanned<ToDecimal>,
     ) -> SourceResult<Decimal> {
         match value.v {

crates/typst/src/foundations/float.rs

@@ -97,7 +97,7 @@ impl f64 {
     ///
     /// - If the number is positive (including `{+0.0}`), returns `{1.0}`.
     /// - If the number is negative (including `{-0.0}`), returns `{-1.0}`.
-    /// - If the number is `{float.nan}`, returns `{float.nan}`.
+    /// - If the number is NaN, returns `{float.nan}`.
     ///
     /// ```example
     /// #(5.0).signum() \

crates/typst/src/introspection/location.rs

@@ -85,8 +85,8 @@ impl Location {
     /// local numbering. This is useful if you are building custom indices or
     /// outlines.
     ///
-    /// If the page numbering is set to `none` at that location, this function
+    /// If the page numbering is set to `{none}` at that location, this function
-    /// returns `none`.
+    /// returns `{none}`.
     #[func]
     pub fn page_numbering(self, engine: &mut Engine) -> Option<Numbering> {
         engine.introspector.page_numbering(self).cloned()

crates/typst/src/layout/align.rs

@@ -64,6 +64,15 @@ use crate::text::TextElem;
 ///   left.
 /// ])
 /// ```
+///
+/// # Alignment within the same line
+/// The `align` function performs block-level alignment and thus always
+/// interrupts the current paragraph. To have different alignment for parts
+/// of the same line, you should use [fractional spacing]($h) instead:
+///
+/// ```example
+/// Start #h(1fr) End
+/// ```
 #[elem(Show)]
 pub struct AlignElem {
     /// The [alignment] along both axes.

crates/typst/src/layout/measure.rs

@@ -19,8 +19,8 @@ use crate::syntax::Span;
 ///
 /// # Example
 /// The same content can have a different size depending on the [context] that
-/// it is placed into. For example, in the example below `[#content]` is of
+/// it is placed into. In the example below, the `[#content]` is of course
-/// course bigger when we increase the font size.
+/// bigger when we increase the font size.
 ///
 /// ```example
 /// #let content = [Hello!]
@@ -53,12 +53,12 @@ pub fn measure(
     span: Span,
     /// The width available to layout the content.
     ///
-    /// Defaults to `{auto}`, which denotes an infinite width.
+    /// Setting this to `{auto}` indicates infinite available width.
     ///
-    /// Using the `width` and `height` parameters of this function is
+    /// Note that using the `width` and `height` parameters of this function is
-    /// different from measuring a [`box`] containing the content;
+    /// different from measuring a sized [`block`] containing the content. In
-    /// the former will get the dimensions of the inner content
+    /// the following example, the former will get the dimensions of the inner
-    /// instead of the dimensions of the box:
+    /// content instead of the dimensions of the block.
     ///
     /// ```example
     /// #context measure(lorem(100), width: 400pt)
@@ -70,7 +70,7 @@ pub fn measure(
     width: Smart<Length>,
     /// The height available to layout the content.
     ///
-    /// Defaults to `{auto}`, which denotes an infinite height.
+    /// Setting this to `{auto}` indicates infinite available height.
     #[named]
     #[default(Smart::Auto)]
     height: Smart<Length>,

crates/typst/src/layout/page.rs

@@ -189,8 +189,8 @@ pub struct PageElem {
     ///
     /// When set to `{none}`, the background becomes transparent. Note that PDF
     /// pages will still appear with a (usually white) background in viewers,
-    /// but they are conceptually transparent. (If you print them, no color is
+    /// but they are actually transparent. (If you print them, no color is used
-    /// used for the background.)
+    /// for the background.)
     ///
     /// The default of `{auto}` results in `{none}` for PDF output, and
     /// `{white}` for PNG and SVG.

crates/typst/src/layout/place.rs

@@ -24,7 +24,7 @@ use crate::layout::{Alignment, Em, Length, Rel};
 ///
 /// # Examples
 /// ```example
-/// #set page(height: 60pt)
+/// #set page(height: 120pt)
 /// Hello, world!
 ///
 /// #rect(

crates/typst/src/layout/spacing.rs

@@ -11,13 +11,23 @@ use crate::utils::Numeric;
 /// # Example
 /// ```example
 /// First #h(1cm) Second \
-/// First #h(30%) Second \
+/// First #h(30%) Second
+/// ```
+///
+/// # Fractional spacing
+/// With fractional spacing, you can align things within a line without forcing
+/// a paragraph break (like [`align`] would). Each fractionally sized element
+/// gets space based on the ratio of its fraction to the sum of all fractions.
+///
+/// ```example
+/// First #h(1fr) Second \
+/// First #h(1fr) Second #h(1fr) Third \
 /// First #h(2fr) Second #h(1fr) Third
 /// ```
 ///
 /// # Mathematical Spacing { #math-spacing }
 /// In [mathematical formulas]($category/math), you can additionally use these
-/// constants to add spacing between elements: `thin` (1/6 em), `med`(2/9 em),
+/// constants to add spacing between elements: `thin` (1/6 em), `med` (2/9 em),
 /// `thick` (5/18 em), `quad` (1 em), `wide` (2 em).
 #[elem(title = "Spacing (H)")]
 pub struct HElem {

crates/typst/src/math/equation.rs

@@ -43,6 +43,9 @@ use crate::World;
 /// $ sum_(k=1)^n k = (n(n+1)) / 2 $
 /// ```
 ///
+/// By default, block-level equations will not break across pages. This can be
+/// changed through `{show math.equation: set block(breakable: true)}`.
+///
 /// # Syntax
 /// This function also has dedicated syntax: Write mathematical markup within
 /// dollar signs to create an equation. Starting and ending the equation with at

crates/typst/src/math/matrix.rs

@@ -40,6 +40,10 @@ const DEFAULT_STROKE_THICKNESS: Em = Em::new(0.05);
 pub struct VecElem {
     /// The delimiter to use.
     ///
+    /// Can be a single character specifying the left delimiter, in which case
+    /// the right delimiter is inferred. Otherwise, can be an array containing a
+    /// left and a right delimiter.
+    ///
     /// ```example
     /// #set math.vec(delim: "[")
     /// $ vec(1, 2) $
@@ -113,6 +117,10 @@ impl LayoutMath for Packed<VecElem> {
 pub struct MatElem {
     /// The delimiter to use.
     ///
+    /// Can be a single character specifying the left delimiter, in which case
+    /// the right delimiter is inferred. Otherwise, can be an array containing a
+    /// left and a right delimiter.
+    ///
     /// ```example
     /// #set math.mat(delim: "[")
     /// $ mat(1, 2; 3, 4) $
@@ -300,6 +308,10 @@ impl LayoutMath for Packed<MatElem> {
 pub struct CasesElem {
     /// The delimiter to use.
     ///
+    /// Can be a single character specifying the left delimiter, in which case
+    /// the right delimiter is inferred. Otherwise, can be an array containing a
+    /// left and a right delimiter.
+    ///
     /// ```example
     /// #set math.cases(delim: "[")
     /// $ x = cases(1, 2) $

crates/typst/src/model/document.rs

@@ -14,7 +14,7 @@ use crate::layout::Page;
 /// All documents are automatically wrapped in a `document` element. You cannot
 /// create a document element yourself. This function is only used with
 /// [set rules]($styling/#set-rules) to specify document metadata. Such a set
-/// rule must appear before any of the document's contents.
+/// rule must not occur inside of any layout container.
 ///
 /// ```example
 /// #set document(title: [Hello])

crates/typst/src/model/enum.rs

@@ -75,9 +75,10 @@ use crate::text::TextElem;
 /// part of that item.
 #[elem(scope, title = "Numbered List", Show)]
 pub struct EnumElem {
-    /// If this is `{false}`, the items are spaced apart with
+    /// Defines the default [spacing]($enum.spacing) of the enumeration. If it
-    /// [enum spacing]($enum.spacing). If it is `{true}`, they use normal
+    /// is `{false}`, the items are spaced apart with
-    /// [leading]($par.leading) instead. This makes the enumeration more
+    /// [paragraph spacing]($par.spacing). If it is `{true}`, they use
+    /// [paragraph leading]($par.leading) instead. This makes the list more
     /// compact, which can look better if the items are short.
     ///
     /// In markup mode, the value of this parameter is determined based on

crates/typst/src/model/footnote.rs

@@ -176,8 +176,8 @@ cast! {
 
 /// An entry in a footnote list.
 ///
-/// This function is not intended to be called directly. Instead, it is used
+/// This function is not intended to be called directly. Instead, it is used in
-/// in set and show rules to customize footnote listings.
+/// set and show rules to customize footnote listings.
 ///
 /// ```example
 /// #show footnote.entry: set text(red)
@@ -187,11 +187,10 @@ cast! {
 /// has red text!
 /// ```
 ///
-/// _Note:_ Set and show rules for `footnote.entry` must be defined at the
+/// _Note:_ Footnote entry properties must be uniform across each page run (a
-/// beginning of the document in order to work correctly. See [here][issue] for
+/// page run is a sequence of pages without an explicit pagebreak in between).
-/// more information.
+/// For this reason, set and show rules for footnote entries should be defined
-///
+/// before any page content, typically at the very start of the document.
-/// [issue]: https://github.com/typst/typst/issues/1467#issuecomment-1588799440
 #[elem(name = "entry", title = "Footnote Entry", Show, ShowSet)]
 pub struct FootnoteEntry {
     /// The footnote for this entry. It's location can be used to determine

crates/typst/src/model/list.rs

@@ -47,10 +47,11 @@ use crate::text::TextElem;
 /// more than an item's marker becomes part of that item.
 #[elem(scope, title = "Bullet List", Show)]
 pub struct ListElem {
-    /// If this is `{false}`, the items are spaced apart with
+    /// Defines the default [spacing]($list.spacing) of the list. If it is
-    /// [list spacing]($list.spacing). If it is `{true}`, they use normal
+    /// `{false}`, the items are spaced apart with
-    /// [leading]($par.leading) instead. This makes the list more compact, which
+    /// [paragraph spacing]($par.spacing). If it is `{true}`, they use
-    /// can look better if the items are short.
+    /// [paragraph leading]($par.leading) instead. This makes the list more
+    /// compact, which can look better if the items are short.
     ///
     /// In markup mode, the value of this parameter is determined based on
     /// whether items are separated with a blank line. If items directly follow

crates/typst/src/model/outline.rs

@@ -172,7 +172,7 @@ pub struct OutlineElem {
     pub indent: Option<Smart<OutlineIndent>>,
 
     /// Content to fill the space between the title and the page number. Can be
-    /// set to `none` to disable filling.
+    /// set to `{none}` to disable filling.
     ///
     /// ```example
     /// #outline(fill: line(length: 100%))

crates/typst/src/model/par.rs

@@ -217,8 +217,11 @@ impl Unlabellable for Packed<ParbreakElem> {}
 
 /// A paragraph line.
 ///
-/// This element is exclusively used for line number configuration and cannot
+/// This element is exclusively used for line number configuration through set
-/// be placed.
+/// rules and cannot be placed.
+///
+/// The [`numbering`]($par.line.numbering) option is used to enable line
+/// numbers by specifying a numbering format.
 ///
 /// ```example
 /// >>> #set page(margin: (left: 3em))
@@ -228,6 +231,43 @@ impl Unlabellable for Packed<ParbreakElem> {}
 /// Violets are blue. \
 /// Typst is there for you.
 /// ```
+///
+/// The `numbering` option takes either a predefined
+/// [numbering pattern]($numbering) or a function returning styled content. You
+/// can disable line numbers for text inside certain elements by setting the
+/// numbering to `{none}` using show-set rules.
+///
+/// ```example
+/// >>> #set page(margin: (left: 3em))
+/// // Styled red line numbers.
+/// #set par.line(
+///   numbering: n => text(red)[#n]
+/// )
+///
+/// // Disable numbers inside figures.
+/// #show figure: set par.line(
+///   numbering: none
+/// )
+///
+/// Roses are red. \
+/// Violets are blue.
+///
+/// #figure(
+///   caption: [Without line numbers.]
+/// )[
+///   Lorem ipsum \
+///   dolor sit amet
+/// ]
+///
+/// The text above is a sample \
+/// originating from distant times.
+/// ```
+///
+/// This element exposes further options which may be used to control other
+/// aspects of line numbering, such as its [alignment]($par.line.number-align)
+/// or [margin]($par.line.number-margin). In addition, you can control whether
+/// the numbering is reset on each page through the
+/// [`numbering-scope`]($par.line.numbering-scope) option.
 #[elem(name = "line", title = "Paragraph Line", keywords = ["line numbering"], Construct, Locatable)]
 pub struct ParLine {
     /// How to number each line. Accepts a
@@ -246,13 +286,16 @@ pub struct ParLine {
 
     /// The alignment of line numbers associated with each line.
     ///
-    /// The default of `auto` will provide a smart default where numbers grow
+    /// The default of `{auto}` indicates a smart default where numbers grow
     /// horizontally away from the text, considering the margin they're in and
     /// the current text direction.
     ///
     /// ```example
     /// >>> #set page(margin: (left: 3em))
-    /// #set par.line(numbering: "I", number-align: left)
+    /// #set par.line(
+    ///   numbering: "I",
+    ///   number-align: left,
+    /// )
     ///
     /// Hello world! \
     /// Today is a beautiful day \
@@ -263,9 +306,18 @@ pub struct ParLine {
 
     /// The margin at which line numbers appear.
     ///
+    /// _Note:_ In a multi-column document, the line numbers for paragraphs
+    /// inside the last column will always appear on the `{end}` margin (right
+    /// margin for left-to-right text and left margin for right-to-left),
+    /// regardless of this configuration. That behavior cannot be changed at
+    /// this moment.
+    ///
     /// ```example
     /// >>> #set page(margin: (right: 3em))
-    /// #set par.line(numbering: "1", number-margin: right)
+    /// #set par.line(
+    ///   numbering: "1",
+    ///   number-margin: right,
+    /// )
     ///
     /// = Report
     /// - Brightness: Dark, yet darker
@@ -284,7 +336,7 @@ pub struct ParLine {
     /// >>> #set page(margin: (left: 3em))
     /// #set par.line(
     ///   numbering: "1",
-    ///   number-clearance: 4pt
+    ///   number-clearance: 4pt,
     /// )
     ///
     /// Typesetting \
@@ -297,14 +349,16 @@ pub struct ParLine {
 
     /// Controls when to reset line numbering.
     ///
-    /// Possible options are `"document"`, indicating the line number counter
+    /// _Note:_ The line numbering scope must be uniform across each page run (a
-    /// is never reset, or `"page"`, indicating it is reset on every page.
+    /// page run is a sequence of pages without an explicit pagebreak in
+    /// between). For this reason, set rules for it should be defined before any
+    /// page content, typically at the very start of the document.
     ///
     /// ```example
     /// >>> #set page(margin: (left: 3em))
     /// #set par.line(
     ///   numbering: "1",
-    ///   numbering-scope: "page"
+    ///   numbering-scope: "page",
     /// )
     ///
     /// First line \

crates/typst/src/model/terms.rs

@@ -27,10 +27,11 @@ use crate::utils::Numeric;
 /// followed by a term, a colon and a description creates a term list item.
 #[elem(scope, title = "Term List", Show)]
 pub struct TermsElem {
-    /// If this is `{false}`, the items are spaced apart with
+    /// Defines the default [spacing]($terms.spacing) of the term list. If it is
-    /// [term list spacing]($terms.spacing). If it is `{true}`, they use normal
+    /// `{false}`, the items are spaced apart with
-    /// [leading]($par.leading) instead. This makes the term list more compact,
+    /// [paragraph spacing]($par.spacing). If it is `{true}`, they use
-    /// which can look better if the items are short.
+    /// [paragraph leading]($par.leading) instead. This makes the list more
+    /// compact, which can look better if the items are short.
     ///
     /// In markup mode, the value of this parameter is determined based on
     /// whether items are separated with a blank line. If items directly follow

crates/typst/src/text/mod.rs

@@ -445,9 +445,10 @@ pub struct TextElem {
     /// 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
+    /// output, please get in touch with us through the
-    /// [contact form](https://typst.app/contact) or our
+    /// [Forum](https://forum.typst.app/),
-    /// [Discord server](https://discord.gg/2uDybryKPe)!
+    /// [Discord server](https://discord.gg/2uDybryKPe),
+    /// or our [contact form](https://typst.app/contact).
     ///
     /// ```example
     /// #set text(dir: rtl)
@@ -482,8 +483,9 @@ pub struct TextElem {
 
     /// The "cost" of various choices when laying out text. A higher cost means
     /// the layout engine will make the choice less often. Costs are specified
-    /// as a ratio of the default cost, so `50%` will make text layout twice as
+    /// as a ratio of the default cost, so `{50%}` will make text layout twice
-    /// eager to make a given choice, while `200%` will make it half as eager.
+    /// as eager to make a given choice, while `{200%}` will make it half as
+    /// eager.
     ///
     /// Currently, the following costs can be customized:
     /// - `hyphenation`: splitting a word across multiple lines
@@ -501,10 +503,10 @@ pub struct TextElem {
     /// Text layout prevents widows and orphans by default because they are
     /// generally discouraged by style guides. However, in some contexts they
     /// are allowed because the prevention method, which moves a line to the
-    /// next page, can result in an uneven number of lines between pages.
+    /// next page, can result in an uneven number of lines between pages. The
-    /// The `widow` and `orphan` costs allow disabling these modifications.
+    /// `widow` and `orphan` costs allow disabling these modifications.
-    /// (Currently, 0% allows widows/orphans; anything else, including the
+    /// (Currently, `{0%}` allows widows/orphans; anything else, including the
-    /// default of `auto`, prevents them. More nuanced cost specification for
+    /// default of `{100%}`, prevents them. More nuanced cost specification for
     /// these modifications is planned for the future.)
     ///
     /// ```example
@@ -568,9 +570,9 @@ pub struct TextElem {
     /// This can be set to an integer or an array of integers, all
     /// of which must be between `{1}` and `{20}`, enabling the
     /// corresponding OpenType feature(s) from `ss01` to `ss20`.
-    /// Setting this to `none` will disable all stylistic sets.
+    /// Setting this to `{none}` will disable all stylistic sets.
     ///
-    /// ```
+    /// ```example
     /// #set text(font: "IBM Plex Serif")
     /// ß vs #text(stylistic-set: 5)[ß] \
     /// 10 years ago vs #text(stylistic-set: (1, 2, 3))[10 years ago]

crates/typst/src/text/raw.rs

@@ -215,7 +215,7 @@ pub struct RawElem {
     pub syntaxes_data: Vec<Bytes>,
 
     /// The theme to use for syntax highlighting. Theme files should be in the
-    /// in the [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html).
+    /// [`tmTheme` file format](https://www.sublimetext.com/docs/color_schemes_tmtheme.html).
     ///
     /// Applying a theme only affects the color of specifically highlighted
     /// text. It does not consider the theme's foreground and background
@@ -224,7 +224,7 @@ pub struct RawElem {
     /// the background with a [filled block]($block.fill). You could also use
     /// the [`xml`] function to extract these properties from the theme.
     ///
-    /// Additionally, you can set the theme to `none` to disable highlighting.
+    /// Additionally, you can set the theme to `{none}` to disable highlighting.
     ///
     /// ````example
     /// #set raw(theme: "halcyon.tmTheme")

crates/typst/src/visualize/line.rs

@@ -33,13 +33,13 @@ pub struct LineElem {
     #[resolve]
     pub end: Option<Axes<Rel<Length>>>,
 
-    /// The line's length. This is only respected if `end` is `none`.
+    /// The line's length. This is only respected if `end` is `{none}`.
     #[resolve]
     #[default(Abs::pt(30.0).into())]
     pub length: Rel<Length>,
 
     /// The angle at which the line points away from the origin. This is only
-    /// respected if `end` is `none`.
+    /// respected if `end` is `{none}`.
     pub angle: Angle,
 
     /// How to [stroke] the line.

docs/changelog.md

@@ -12,20 +12,20 @@ description: |
   [figures]($figure.scope)
 - Added support for automatic [line numbering]($par.line) (often used in
   academic papers)
-- Typst's layout engine is now multi-threaded. Typical speedups are 2-3x for
+- Typst's layout engine is now multithreaded. Typical speedups are 2-3x for
-  larger documents. The multi-threading operates on page break boundaries, so
+  larger documents. The multithreading operates on page break boundaries, so
   explicit page breaks are necessary for it to kick in.
 - Paragraph justification was optimized with a new two-pass algorithm. Speedups
-  are larger for shorter paragraphs and range from 1-6x.
+  are larger for shorter paragraphs and go up to 6x.
 - Highly reduced PDF file sizes due to better font subsetting (thanks to
   [@LaurenzV](https://github.com/LaurenzV))
 - Emoji are now exported properly in PDF
-- Added initial support for PDF/A. For now, only the standard PDF/A-2b is
+- Added initial support for PDF/A. For now, only the PDF/A-2b profile is
   supported, but more is planned for the future.
 - Added various options for configuring the CLI's environment (fonts, package
   paths, etc.)
 - Text show rules now match across multiple text elements
-- Block-level equations can now break over multiple pages
+- Block-level equations can now optionally break over multiple pages
 - Fixed a bug where some fonts would not print correctly on professional
   printers
 - Fixed a long-standing bug which could cause headings to be orphaned at the
@@ -42,6 +42,9 @@ description: |
   - Added [`par.spacing`] property for configuring paragraph spacing. This
     should now be used instead of `{show par: set block(spacing: ..)}`
     (**Breaking change**)
+  - Block-level elements like lists, grids, and stacks now show themselves as
+    blocks and are thus affected by all block properties (e.g. `stroke`) rather
+    than just `spacing` (**Breaking change**)
   - Added [`block.sticky`] property which prevents a page break after a block
   - Added [`place.flush`] function which forces all floating figures to be
     placed before any further content
@@ -55,18 +58,20 @@ description: |
     combination with [`layout`].
   - The height of a `block`, `image`, `rect`, `square`, `ellipse`, or `circle`
     can now be specified in [fractional units]($fraction)
-  - The [`scale`] function now supports non-relative lengths for `x` and `y`.
+  - The [`scale`] function now supports absolute lengths for `x`, `y`, `factor`.
     This way an element of unknown size can be scaled to a fixed size.
   - The values of `block.above` and `block.below` can now be retrieved in
     context expressions.
+  - Increased accuracy of conversions between absolute units (pt, mm, cm, in)
   - Fixed a bug which could cause headings to be orphaned at the bottom of the
     page
   - Fixed footnotes within breakable blocks appearing on the page where the
     breakable block ends instead of at the page where the footnote marker is
+  - Fixed numbering of nested footnotes and footnotes in floats
   - Fixed empty pages appearing when a [context] expression wraps whole pages
   - Fixed `{set block(spacing: x)}` behaving differently from
     `{set block(above: x, below: x)}`
-  - Fixed behaviour of [`rotate`] and [`scale`] with `{reflow: true}`
+  - Fixed behavior of [`rotate`] and [`scale`] with `{reflow: true}`
   - Fixed interaction of `{align(horizon)}` and `{v(1fr)}`
   - Fixed various bugs where floating placement would yield overlapping results
   - Fixed a bug where widow/orphan prevention would unnecessarily move text into
@@ -113,8 +118,8 @@ description: |
   - Updated bundled New Computer Modern fonts to version 6.0
 
 - Math
-  - Block-level equations can now break over multiple pages. This behaviour can
+  - Block-level equations can now break over multiple pages if enabled via
-    be disabled via `{show math.equation: set block(breakable: false)}`.
+    `{show math.equation: set block(breakable: true)}`.
   - Matrix and vector sizing is now more consistent across different cell
     contents
   - Added [`stretch`]($math.stretch) function for manually or automatically
@@ -124,10 +129,11 @@ description: |
   - Improved layout of nested attachments resulting from code like
     `[#let a0 = $a_0$; $a0^1$]`
   - Improved layout of primes close to superscripts
-  - Typst now makes use of math-specific height-dependant kerning information in
+  - Improved layout of fractions
+  - Typst now makes use of math-specific height-dependent kerning information in
     some fonts for better attachment layout
-  - The `floor` and `ceil` functions in math are now callable symbols instead,
+  - The `floor` and `ceil` functions in math are now callable symbols, such that
-    such that `[$ floor(x) = lr(floor.l x floor.r) $]`
+    `[$ floor(x) = lr(floor.l x floor.r) $]`
   - The [`mat.delim`]($math.mat.delim), [`vec.delim`]($math.vec.delim), and
     [`cases.delim`]($math.cases.delim) parameters now allow any character that
     is considered a delimiter or "fence" (e.g. |) by Unicode. The
@@ -136,8 +142,8 @@ description: |
   - Added [`vec.align`]($math.vec.align) and [`mat.align`]($math.mat.align)
     parameters
   - Added [`underparen`]($math.underparen), [`overparen`]($math.overparen),
-    [`undershell`]($math.undershell), and [`overshell`]($math.underparen)
+    [`undershell`]($math.undershell), and [`overshell`]($math.overshell)
-  - Added `~` shorthand for `tilde.op` (**Minor breaking change**)
+  - Added `~` shorthand for `tilde.op` in math mode (**Minor breaking change**)
   - Fixed baseline alignment of equation numbers
   - Fixed positioning of corner brackets (⌜, ⌝, ⌞, ⌟)
   - Fixed baseline of large roots
@@ -148,21 +154,25 @@ description: |
   - Fixed a crash with recursive show rules in math
   - Fixed [`lr.size`]($math.lr.size) not affecting characters enclosed in
     [`mid`]($math.mid) in some cases
+  - Fixed resolving of em units in sub- and superscripts
+  - Fixed bounding box of inline equations when a [text edge]($text.top-edge) is
+    set to `{"bounds"}`
 
 - Introspection
   - Implemented a new system by which Typst tracks where elements end up on the
-    pages. This may lead to subtly different behaviour in introspections.
+    pages. This may lead to subtly different behavior in introspections.
     (**Breaking change**)
-  - Fixed various bugs with wrong counter behaviour in complex layout
+  - Fixed various bugs with wrong counter behavior in complex layout
     situations, through a new, more principled implementation
   - Counter updates can now be before the first, in between, and after the last
     page when isolated by weak page breaks. This allows, for instance, updating
     a counter before the first page header and background.
+  - Fixed logical ordering of introspections within footnotes and figures
   - Fixed incorrect [`here().position()`]($here) when [`place`] was used in a
     context expression
   - Fixed resolved positions of elements (in particular, headings) whose show
     rule emits an invisible element (like a state update) before a page break
-  - Fixed behaviour of stepping a counter at a deeper level that its current
+  - Fixed behavior of stepping a counter at a deeper level than its current
     state has
   - Fixed citation formatting not working in table headers and a few other
     places
@@ -231,8 +241,8 @@ description: |
   - Fixed rare crash in parsing of parenthesized expressions
 
 - Scripting
-  - Added new fixed-point [`decimal`] number type for when highly precise
+  - Added new fixed-point [`decimal`] number type for highly precise arithmetic
-    arithmetic is needed, such as for finance
+    on numbers in base 10, as needed for finance
   - Added `std` module for accessing standard library definitions even when a
     variable with the same name shadows/overwrites it
   - Added [`array.to-dict`], [`array.reduce`], [`array.windows`] methods
@@ -240,18 +250,20 @@ description: |
   - Added [`arguments.at`] method
   - Added [`int.from-bytes`], [`int.to-bytes`], [`float.from-bytes`], and
     [`float.to-bytes`]
-  - [`calc.round`] no longer accepts negative digits (**Minor breaking change**)
+  - Added proper support for negative values of the `digits` parameter of
+    [`calc.round`] (the behaviour existed before but was subtly broken)
   - Conversions from [`int`] to [`float`] will now error instead of saturating
     if the float is too large (**Minor breaking change**)
   - Added `float.nan` and `float.inf`, removed `calc.nan`
     (**Minor breaking change**)
   - Certain symbols are now generally callable like functions and not only
-    specifically in math. Examples are accents or `floor` and `ceil`.
+    specifically in math. Examples are accents or [`floor`]($math.floor) and
+    [`ceil`]($math.ceil).
   - Improved [`repr`] of relative values, sequences, infinities, NaN,
     `{type(none)}` and `{type(auto)}`
   - Fixed crash on whole packages (rather than just files) cyclically importing
     each other
-  - Fixed behaviour of [`calc.round`] on integers when a non-zero value is
+  - Fixed return type of [`calc.round`] on integers when a non-zero value is
     provided for `digits`
 
 - Styling
@@ -280,11 +292,12 @@ description: |
   - Fixed a bug where transparency could leak from one PDF object to another
   - Fixed a bug with CMYK gradients in PDF
   - Fixed various bugs with export of Oklab gradients in PDF
+  - Fixed crashes related to rendering of non-outline glyphs
   - Two small fixes for PDF standard conformance
 
 - Performance
-  - Typst's layout engine is now multi-threaded. Typical speedups are 2-3x for
+  - Typst's layout engine is now multithreaded. Typical speedups are 2-3x for
-    larger documents. The multi-threading operates on page break boundaries, so
+    larger documents. The multithreading operates on page break boundaries, so
     explicit page breaks are necessary for it to kick in.
   - Paragraph justification was optimized with a new two-pass algorithm.
     Speedups are larger for shorter paragraphs and range from 1-6x.
@@ -299,9 +312,11 @@ description: |
   - Added `--make-deps` argument for outputting the dependencies of the current
     compilation as a Makefile
   - Added `--pretty` option to `typst query`, with the default now being to
-    minify
+    minify (only applies to JSON format)
   - Added `--backup-path` to `typst update` to configure where the previous
     version is backed up
+  - Added useful links to help output
+  - The CLI will now greet users who invoke just `typst` for the first time
   - The document can now be written to stdout by passing `-` as the output
     filename (for PDF or single-page image export)
   - Typst will now emit a proper error message instead of failing silently when
@@ -381,7 +396,7 @@ description: |
   - Added `typst-kit` crate which provides useful APIs for `World` implementors
   - Added go-to-definition API in `typst-ide`
   - Added package manifest parsing APIs to `typst-syntax`
-  - As the compiler is now capable of multi-threading, `World` implementations
+  - As the compiler is now capable of multithreading, `World` implementations
     must satisfy `Send` and `Sync`
   - Changed signature of `World::main` to allow for the scenario where the main
     file could not be loaded
@@ -725,7 +740,7 @@ description: |
   - Fixed missing title in some bibliography styles
   - Fixed printing of volumes in some styles
   - Fixed delimiter order for contributors in some styles (e.g. APA)
-  - Fixed behaviour of alphanumeric style
+  - Fixed behavior of alphanumeric style
   - Fixed multiple bugs with GB/T 7714 style
   - Fixed escaping in Hayagriva values
   - Fixed crashes with empty dates in Hayagriva files
@@ -915,7 +930,7 @@ description: |
   - Fixed line breaking of composite emoji like 🏳️‍🌈
   - Fixed missing text in some SVGs
   - Fixed font fallback in SVGs
-  - Fixed behaviour of [`to`]($pagebreak.to) argument on `pagebreak` function
+  - Fixed behavior of [`to`]($pagebreak.to) argument on `pagebreak` function
   - Fixed `{set align(..)}` for equations
   - Fixed spacing around [placed]($place) elements
   - Fixed coalescing of [`above`]($block.above) and [`below`]($block.below)
@@ -1513,7 +1528,7 @@ description: |
   - Renamed a few symbols: What was previous `dot.op` is now just `dot` and the
     basic dot is `dot.basic`. The same applies to `ast` and `tilde`.
   - Renamed `mod` to [`rem`]($calc.rem) to more accurately reflect the
-    behaviour. It will remain available as `mod` until the next update as a
+    behavior. It will remain available as `mod` until the next update as a
     grace period.
   - A lone underscore is not a valid identifier anymore, it can now only be used
     in patterns
@@ -1635,7 +1650,7 @@ description: |
     `{"chicago-author-title"}`
 
 - Figure improvements
-  - Figures now automatically detect their content and adapt their behaviour.
+  - Figures now automatically detect their content and adapt their behavior.
     Figures containing tables, for instance, are automatically prefixed with
     "Table X" and have a separate counter
   - The figure's supplement (e.g. "Figure" or "Table") can now be customized

docs/guides/tables.md

@@ -527,7 +527,7 @@ is useful if you are writing a template or want to style your whole document.
 ```
 
 For small tables, you sometimes want to suppress all strokes because they add
-too much visual noise. To do this, just set the stroke argument to `none`:
+too much visual noise. To do this, just set the stroke argument to `{none}`:
 
 ```example
 #table(

docs/reference/groups.yml

@@ -128,7 +128,7 @@
 
     These definitions are part of the `calc` module and not imported by default.
     In addition to the functions listed below, the `calc` module also defines
-    the constants `pi`, `tau`, `e`, `inf`, and `nan`.
+    the constants `pi`, `tau`, `e`, and `inf`.
 
 - name: sys
   title: System

docs/reference/scripting.md

@@ -302,7 +302,8 @@ ways:
 - **Import:** `{import "bar.typ"}` \
   Evaluates the file at the path `bar.typ` and inserts the resulting [module]
   into the current scope as `bar` (filename without extension). You can use the
-  `as` keyword to rename the imported module: `{import "bar.typ" as baz}`
+  `as` keyword to rename the imported module: `{import "bar.typ" as baz}`. You
+  can import nested items using dot notation: `{import "bar.typ": baz.a}`.
 
 - **Import items:** `{import "bar.typ": a, b}` \
   Evaluates the file at the path `bar.typ`, extracts the values of the variables

docs/tutorial/4-template.md

@@ -361,7 +361,7 @@ want to import.
 ```
 
 We have now converted the conference paper into a reusable template for that
-conference! Why not share it on
+conference! Why not share it in the [Forum](https://forum.typst.app/) or on
 [Typst's Discord server](https://discord.gg/2uDybryKPe) so that others can use
 it too?
 
@@ -372,9 +372,10 @@ that define reusable document styles. You've made it far and learned a lot. You
 can now use Typst to write your own documents and share them with others.
 
 We are still a super young project and are looking for feedback. If you have any
-questions, suggestions or you found a bug, please let us know on
+questions, suggestions or you found a bug, please let us know
-[Typst's Discord server](https://discord.gg/2uDybryKPe), on our
+in the [Forum](https://forum.typst.app/),
-[contact form](https://typst.app/contact), or on
+on our [Discord server](https://discord.gg/2uDybryKPe),
-[social media.](https://twitter.com/typstapp)
+on [GitHub](https://github.com/typst/typst/),
+or via the web app's feedback form (always available in the Help menu).
 
 So what are you waiting for? [Sign up](https://typst.app) and write something!