Docs and changelog improvements (#5147)

Co-authored-by: Malo <[email protected]>
Co-authored-by: Andrew Voynov <[email protected]>
Co-authored-by: PgBiel <[email protected]>
Co-authored-by: Jeremie Knuesel <[email protected]>
Co-authored-by: +merlan #flirora <[email protected]>
Co-authored-by: Anselm Schüler <[email protected]>

Author: 7 people

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)}`
-/// - note the lack of double quotes, indicating this is an accidental `float`
-/// cast and therefore imprecise).
+/// 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`
+/// 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
-    /// returns `none`.
+    /// If the page numbering is set to `{none}` at that location, this function
+    /// 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
-/// course bigger when we increase the font size.
+/// it is placed into. In the example below, the `[#content]` is of course
+/// 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
-    /// different from measuring a [`box`] containing the content;
-    /// the former will get the dimensions of the inner content
-    /// instead of the dimensions of the box:
+    /// Note that using the `width` and `height` parameters of this function is
+    /// different from measuring a sized [`block`] containing the content. In
+    /// the following example, the former will get the dimensions of the inner
+    /// 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
-    /// used for the background.)
+    /// but they are actually transparent. (If you print them, no color is used
+    /// for the background.)
     ///
     /// The default of `{auto}` results in `{none}` for PDF output, and
     /// `{white}` for PNG and SVG.