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>

1 files changed, 45 insertions, 30 deletions

diff --git a/docs/changelog.md b/docs/changelog.md
index 2027f986..f88aacea 100644
--- a/docs/changelog.md
+++ b/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
-  larger documents. The multi-threading operates on page break boundaries, so
+- Typst's layout engine is now multithreaded. Typical speedups are 2-3x for
+  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
-    be disabled via `{show math.equation: set block(breakable: false)}`.
+  - Block-level equations can now break over multiple pages if enabled via
+    `{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,
-    such that `[$ floor(x) = lr(floor.l x floor.r) $]`
+  - The `floor` and `ceil` functions in math are now callable symbols, such that
+    `[$ 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)
-  - Added `~` shorthand for `tilde.op` (**Minor breaking change**)
+    [`undershell`]($math.undershell), and [`overshell`]($math.overshell)
+  - 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
-    arithmetic is needed, such as for finance
+  - Added new fixed-point [`decimal`] number type for highly precise arithmetic
+    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
-    larger documents. The multi-threading operates on page break boundaries, so
+  - Typst's layout engine is now multithreaded. Typical speedups are 2-3x for
+    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