From d446cde4fa2f10c753092761c1ec7e2083512720 Mon Sep 17 00:00:00 2001
From: "Y.D.X." <73375426+YDX-2147483647@users.noreply.github.com>
Date: Mon, 28 Jul 2025 17:39:13 +0800
Subject: [PATCH] Miscellaneous minor docs improvements (#6651)

Co-authored-by: Laurenz <laurmaedje@gmail.com>
---
 .../src/introspection/counter.rs              |  4 +-
 crates/typst-library/src/layout/page.rs       |  9 +++++
 crates/typst-library/src/model/figure.rs      | 37 ++++++++++++++++++-
 crates/typst-library/src/text/mod.rs          |  6 +++
 docs/reference/library/symbols.md             |  3 ++
 5 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/crates/typst-library/src/introspection/counter.rs b/crates/typst-library/src/introspection/counter.rs
index f6083303d..c7d26040c 100644
--- a/crates/typst-library/src/introspection/counter.rs
+++ b/crates/typst-library/src/introspection/counter.rs
@@ -412,9 +412,11 @@ impl Counter {
         /// - If it is a string, creates a custom counter that is only affected
         ///   by manual updates,
         /// - If it is the [`page`] function, counts through pages,
-        /// - If it is a [selector], counts through elements that matches with the
+        /// - If it is a [selector], counts through elements that match the
         ///   selector. For example,
         ///   - provide an element function: counts elements of that type,
+        ///   - provide a [`where`]($function.where) selector:
+        ///     counts a type of element with specific fields,
         ///   - provide a [`{<label>}`]($label): counts elements with that label.
         key: CounterKey,
     ) -> Counter {
diff --git a/crates/typst-library/src/layout/page.rs b/crates/typst-library/src/layout/page.rs
index 64ed99e34..7d586c2c1 100644
--- a/crates/typst-library/src/layout/page.rs
+++ b/crates/typst-library/src/layout/page.rs
@@ -397,6 +397,15 @@ impl LocalName for PageElem {
 /// == Compound Theory
 /// In 1984, the first ...
 /// ```
+///
+/// Even without manual page breaks, content will be automatically paginated
+/// based on the configured page size. You can set [the page height]($page.height)
+/// to `{auto}` to let the page grow dynamically until a manual page break
+/// occurs.
+///
+/// Pagination tries to avoid single lines of text at the top or bottom of a
+/// page (these are called _widows_ and _orphans_). You can adjust the
+/// [`text.costs`]($text.costs) parameter to disable this behavior.
 #[elem(title = "Page Break")]
 pub struct PagebreakElem {
     /// If `{true}`, the page break is skipped if the current page is already
diff --git a/crates/typst-library/src/model/figure.rs b/crates/typst-library/src/model/figure.rs
index daab37e44..d1497db68 100644
--- a/crates/typst-library/src/model/figure.rs
+++ b/crates/typst-library/src/model/figure.rs
@@ -189,6 +189,39 @@ pub struct FigureElem {
     ///   supplement: [Atom],
     /// )
     /// ```
+    ///
+    /// If you want to modify a counter to skip a number or reset the counter,
+    /// you can access the [counter] of each kind of figure with a
+    /// [`where`]($function.where) selector:
+    ///
+    /// - For [tables]($table): `{counter(figure.where(kind: table))}`
+    /// - For [images]($image): `{counter(figure.where(kind: image))}`
+    /// - For a custom kind: `{counter(figure.where(kind: kind))}`
+    ///
+    /// ```example
+    /// #figure(
+    ///   table(columns: 2, $n$, $1$),
+    ///   caption: [The first table.],
+    /// )
+    ///
+    /// #counter(
+    ///   figure.where(kind: table)
+    /// ).update(41)
+    ///
+    /// #figure(
+    ///   table(columns: 2, $n$, $42$),
+    ///   caption: [The 42nd table],
+    /// )
+    ///
+    /// #figure(
+    ///   rect[Image],
+    ///   caption: [Does not affect images],
+    /// )
+    /// ```
+    ///
+    /// To conveniently use the correct counter in a show rule, you can access
+    /// the `counter` field. There is an example of this in the documentation
+    /// [of the `figure.caption` element's `body` field]($figure.caption.body).
     pub kind: Smart<FigureKind>,
 
     /// The figure's supplement.
@@ -228,8 +261,8 @@ pub struct FigureElem {
     /// Convenience field to get access to the counter for this figure.
     ///
     /// The counter only depends on the `kind`:
-    /// - For (tables)[@table]: `{counter(figure.where(kind: table))}`
-    /// - For (images)[@image]: `{counter(figure.where(kind: image))}`
+    /// - For [tables]($table): `{counter(figure.where(kind: table))}`
+    /// - For [images]($image): `{counter(figure.where(kind: image))}`
     /// - For a custom kind: `{counter(figure.where(kind: kind))}`
     ///
     /// These are the counters you'll need to modify if you want to skip a
diff --git a/crates/typst-library/src/text/mod.rs b/crates/typst-library/src/text/mod.rs
index f2025f5b8..c17b8699f 100644
--- a/crates/typst-library/src/text/mod.rs
+++ b/crates/typst-library/src/text/mod.rs
@@ -411,6 +411,9 @@ pub struct TextElem {
     /// = Einleitung
     /// In diesem Dokument, ...
     /// ```
+    ///
+    /// The language code is case-insensitive, and will be lowercased when
+    /// accessed through [context]($context).
     #[default(Lang::ENGLISH)]
     #[ghost]
     pub lang: Lang,
@@ -418,6 +421,9 @@ pub struct TextElem {
     /// An [ISO 3166-1 alpha-2 region code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
     ///
     /// This lets the text processing pipeline make more informed choices.
+    ///
+    /// The region code is case-insensitive, and will be uppercased when
+    /// accessed through [context]($context).
     #[ghost]
     pub region: Option<Region>,
 
diff --git a/docs/reference/library/symbols.md b/docs/reference/library/symbols.md
index 2e6f48cdb..3a955a305 100644
--- a/docs/reference/library/symbols.md
+++ b/docs/reference/library/symbols.md
@@ -3,3 +3,6 @@ with a normal keyboard. Alternatively, you can also always directly enter
 Unicode symbols into your text and formulas. In addition to the symbols listed
 below, math mode defines `dif` and `Dif`. These are not normal symbol values
 because they also affect spacing and font style.
+
+You can define custom symbols with the constructor function of the
+[symbol]($symbol) type.