Document math category

3 files changed, 194 insertions, 19 deletions

diff --git a/library/src/math/matrix.rs b/library/src/math/matrix.rs
index 49527354..1a84d611 100644
--- a/library/src/math/matrix.rs
+++ b/library/src/math/matrix.rs
@@ -3,6 +3,14 @@ use super::*;
 /// # Vector
 /// A column vector.
 ///
+/// _Note:_ Matrices are not yet supported.
+///
+/// ## Example
+/// ```
+/// $ vec(a, b, c) dot vec(1, 2, 3)
+///     = a + 2b + 3c $
+/// ```
+///
 /// ## Parameters
 /// - elements: Content (positional, variadic)
 ///   The elements of the vector.
@@ -16,7 +24,13 @@ pub struct VecNode(Vec<Content>);
 
 #[node]
 impl VecNode {
-    /// The kind of delimiter.
+    /// The delimiter to use.
+    ///
+    /// # Example
+    /// ```
+    /// #set vec(delim: "[")
+    /// $ vec(1, 2) $
+    /// ```
     pub const DELIM: Delimiter = Delimiter::Paren;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
@@ -69,19 +83,29 @@ pub enum Delimiter {
 
 castable! {
     Delimiter,
-    /// Delimit vector with parentheses.
+    /// Delimit the vector with parentheses.
     "(" => Self::Paren,
-    /// Delimit vector with brackets.
+    /// Delimit the vector with brackets.
     "[" => Self::Bracket,
-    /// Delimit vector with curly braces.
+    /// Delimit the vector with curly braces.
     "{" => Self::Brace,
-    /// Delimit vector with vertical bars.
+    /// Delimit the vector with vertical bars.
     "|" => Self::Bar,
 }
 
 /// # Cases
 /// A case distinction.
 ///
+/// ## Example
+/// ```
+/// $ f(x, y) := cases(
+///   1 "if" (x dot y)/2 <= 0,
+///   2 "if" x in NN,
+///   3 "if" x "is even",
+///   4 "else",
+/// ) $
+/// ```
+///
 /// ## Parameters
 /// - branches: Content (positional, variadic)
 ///   The branches of the case distinction.
diff --git a/library/src/math/mod.rs b/library/src/math/mod.rs
index c8d15796..6e6c4104 100644
--- a/library/src/math/mod.rs
+++ b/library/src/math/mod.rs
@@ -15,7 +15,33 @@ use crate::prelude::*;
 use crate::text::{FontFamily, LinebreakNode, SpaceNode, SymbolNode, TextNode};
 
 /// # Math
-/// A piece of a mathematical formula.
+/// A mathematical formula.
+///
+/// _Note:_ Math mode is still rather limited in Typst. We're working hard to
+/// improve it, so please bear with us in the meantime!
+///
+/// ## Syntax
+/// This function also has dedicated syntax: Write mathematical markup within
+/// 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.
+///
+/// ## Example
+/// ```
+/// #set text("Latin Modern Roman")
+///
+/// Let $a$, $b$, and $c$ be the side
+/// lengths of right-angled triangle.
+/// Then, we know that:
+/// $ a^2 + b^2 = c^2 $
+///
+/// Prove by induction:
+/// $ sum_(k=1)^n k = (n(n+1)) / 2 $
+///
+/// We define the following set:
+/// $ cal(A) :=
+///     { x in RR | x "is natural" } $
+/// ```
 ///
 /// ## Parameters
 /// - items: Content (positional, variadic)
@@ -310,13 +336,38 @@ impl Texify for AtomNode {
 /// # Accent
 /// An accented node.
 ///
+/// ## Example
+/// ```
+/// $acc(a, ->) != acc(a, ~)$ \
+/// $acc(a, `) = acc(a, grave)$
+/// ```
+///
 /// ## Parameters
 /// - base: Content (positional, required)
 ///   The base to which the accent is applied.
+///   May consist of multiple letters.
+///
+///   ### Example
+///   ```
+///   $acc(A B C, ->)$
+///   ```
 ///
 /// - accent: Content (positional, required)
 ///   The accent to apply to the base.
 ///
+///   Supported accents include:
+///   - Grave: `` ` ``
+///   - Acute: `´`
+///   - Circumflex: `^`
+///   - Tilde: `~`
+///   - Macron: `¯`
+///   - Overline: `‾`
+///   - Breve: `˘`
+///   - Dot: `.`
+///   - Diaeresis: `¨`
+///   - Caron: `ˇ`
+///   - Arrow: `→`
+///
 /// ## Category
 /// math
 #[func]
@@ -394,7 +445,19 @@ impl Texify for AccNode {
 }
 
 /// # Fraction
-/// A fraction.
+/// A mathematical fraction.
+///
+/// ## 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)
@@ -436,7 +499,12 @@ impl Texify for FracNode {
 }
 
 /// # Binomial
-/// A binomial.
+/// A binomial expression.
+///
+/// ## Example
+/// ```
+/// $ binom(n, k) $
+/// ```
 ///
 /// ## Parameters
 /// - upper: Content (positional, required)
@@ -478,7 +546,19 @@ impl Texify for BinomNode {
 }
 
 /// # Script
-/// A sub- and/or superscript.
+/// A mathematical sub- and/or superscript.
+///
+/// _Note:_ In the future, this might be unified with the [sub](@sub) and
+/// [super](@super) functions that handle sub- and superscripts in text.
+///
+/// ## Syntax
+/// This function also has dedicated syntax: Use the underscore (`_`) to
+/// indicate a subscript and the circumflex (`^`) to indicate a superscript.
+///
+/// ## Example
+/// ```
+/// $ a_i = 2^(1+i) $
+/// ```
 ///
 /// ## Parameters
 /// - base: Content (positional, required)
@@ -564,6 +644,13 @@ impl Texify for AlignPointNode {
 /// # Square Root
 /// A square root.
 ///
+/// _Note:_ Non-square roots are not yet supported.
+///
+/// ## Example
+/// ```
+/// $ sqrt(x^2) = x = sqrt(x)^2 $
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The expression to take the square root of.
@@ -594,6 +681,11 @@ impl Texify for SqrtNode {
 /// # Floor
 /// A floored expression.
 ///
+/// ## Example
+/// ```
+/// $ floor(x/2) $
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The expression to floor.
@@ -624,6 +716,11 @@ impl Texify for FloorNode {
 /// # Ceil
 /// A ceiled expression.
 ///
+/// ## Example
+/// ```
+/// $ ceil(x/2) $
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The expression to ceil.
diff --git a/library/src/math/style.rs b/library/src/math/style.rs
index 4a9c43b8..d272bc94 100644
--- a/library/src/math/style.rs
+++ b/library/src/math/style.rs
@@ -1,7 +1,11 @@
 use super::*;
 
 /// # Serif
-/// Serif (roman) font style.
+/// Serif (roman) font style in math.
+///
+/// This is already the default.
+///
+/// _Note:_ In the future this might be unified with text styling.
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -31,7 +35,14 @@ impl Texify for SerifNode {
 }
 
 /// # Sans-serif
-/// Sans-serif font style.
+/// Sans-serif font style in math.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## Example
+/// ```
+/// $ sans(A B C) $
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -61,7 +72,14 @@ impl Texify for SansNode {
 }
 
 /// # Bold
-/// Bold font style.
+/// Bold font style in math.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## Example
+/// ```
+/// $ bold(A) := B^+ $
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -91,7 +109,11 @@ impl Texify for BoldNode {
 }
 
 /// # Italic
-/// Italic font style.
+/// Italic font style in math.
+///
+/// This is already the default.
+///
+/// _Note:_ In the future this might be unified with text styling.
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -121,7 +143,14 @@ impl Texify for ItalNode {
 }
 
 /// # Calligraphic
-/// Calligraphic font style.
+/// Calligraphic font style in math.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## Example
+/// ```
+/// Let $cal(P)$ be the set of ...
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -151,7 +180,14 @@ impl Texify for CalNode {
 }
 
 /// # Fraktur
-/// Fraktur font style.
+/// Fraktur font style in math.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## Example
+/// ```
+/// $ frak(P) $
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -181,7 +217,14 @@ impl Texify for FrakNode {
 }
 
 /// # Monospace
-/// Monospace font style.
+/// Monospace font style in math.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## Example
+/// ```
+/// $ mono(x + y = z) $
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -211,11 +254,22 @@ impl Texify for MonoNode {
 }
 
 /// # Doublestruck
-/// Blackboard bold (double-struck) font style.
+/// Blackboard bold (double-struck) font style in math.
+///
+/// For uppercase latin letters, blackboard bold is additionally available
+/// through [symmie symbols](@symbol) of the form `NN` and `RR`.
+///
+/// _Note:_ In the future this might be unified with text styling.
+///
+/// ## 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