Math documentation improvements

library/src/math/accent.rs

@@ -29,19 +29,22 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5);
 ///   The accent to apply to the base.
 ///
 ///   Supported accents include:
-///   - Grave: `grave`, `` ` ``
-///   - Acute: `acute`, `´`
-///   - Circumflex: `circum`, `^`
-///   - Tilde: `tilde`, `~`
-///   - Macron: `macron`, `¯`
-///   - Breve: `breve`, `˘`
-///   - Dot: `dot`, `.`
-///   - Diaeresis: `diaer` `¨`
-///   - Circle: `circle`, `∘`
-///   - Double acute: `acute.double`, `˝`
-///   - Caron: `caron`, `ˇ`
-///   - Right arrow: `arrow`, `->`
-///   - Left arrow: `arrow.l`, `<-`
+///
+///   | Accent       | Name            | Codepoint |
+///   | ------------ | --------------- | --------- |
+///   | Grave        | `grave`         | <code>&DiacriticalGrave;</code> |
+///   | Acute        | `acute`         | `´`       |
+///   | Circumflex   | `circum`        | `^`       |
+///   | Tilde        | `tilde`         | `~`       |
+///   | Macron       | `macron`        | `¯`       |
+///   | Breve        | `breve`         | `˘`       |
+///   | Dot          | `dot`           | `.`       |
+///   | Diaeresis    | `diaer`         | `¨`       |
+///   | Circle       | `circle`        | `∘`       |
+///   | Double acute | `acute.double`  | `˝`       |
+///   | Caron        | `caron`         | `ˇ`       |
+///   | Right arrow  | `arrow`, `->`   | `→`       |
+///   | Left arrow   | `arrow.l`, `<-` | `←`       |
 ///
 /// ## Category
 /// math

library/src/math/lr.rs

@@ -3,7 +3,7 @@ use super::*;
 /// How much less high scaled delimiters can be than what they wrap.
 pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1);
 
-/// # Left-Right
+/// # Left/Right
 /// Scales delimiters.
 ///
 /// While matched delimiters scale by default, this can be used to scale

library/src/math/matrix.rs

@@ -7,6 +7,8 @@ const VERTICAL_PADDING: Ratio = Ratio::new(0.1);
 /// # Vector
 /// A column vector.
 ///
+/// Content in the vector's elements can be aligned with the `&` symbol.
+///
 /// ## Example
 /// ```
 /// $ vec(a, b, c) dot vec(1, 2, 3)
@@ -51,15 +53,35 @@ impl LayoutMath for VecNode {
 /// # Matrix
 /// A matrix.
 ///
+/// The elements of a row should be separated by commas, while the rows
+/// themselves should be separated by semicolons. The semicolon syntax merges
+/// preceding arguments separated by commas into a array arguments. You
+/// can also use this special syntax of math function calls to define custom
+/// functions that take 2D data.
+///
+/// Content in cells that are in the same row can be aligned with the `&` symbol.
+///
 /// ## Example
 /// ```
-/// $ mat(1, 2; 3, 4) $
+/// $ mat(
+///   1, 2, ..., 10;
+///   2, 2, ..., 10;
+///   dots.v, dots.v, dots.down, dots.v;
+///   10, 10, ..., 10;
+/// ) $
 /// ```
 ///
 /// ## Parameters
 /// - rows: Array (positional, variadic)
 ///   An array of arrays with the rows of the matrix.
 ///
+///   # Example
+///   ```
+///   #let data = ((1, 2, 3), (4, 5, 6))
+///   #let matrix = math.mat(..data)
+///   $ v := matrix $
+///   ```
+///
 /// ## Category
 /// math
 #[func]
@@ -115,12 +137,14 @@ impl LayoutMath for MatNode {
 /// # Cases
 /// A case distinction.
 ///
+/// Content across different branches can be aligned with the `&` symbol.
+///
 /// ## Example
 /// ```
 /// $ f(x, y) := cases(
 ///   1 "if" (x dot y)/2 <= 0,
-///   2 "if" x in NN,
-///   3 "if" x "is even",
+///   2 "if" x "is even",
+///   3 "if" x in NN,
 ///   4 "else",
 /// ) $
 /// ```

library/src/math/op.rs

@@ -11,7 +11,7 @@ use super::*;
 /// - limits: bool (named)
 ///   Whether the operator should force attachments to display as limits.
 ///
-///   Defaults to `false`.
+///   Defaults to `{false}`.
 ///
 /// ## Category
 /// math

library/src/math/style.rs

@@ -1,40 +1,5 @@
 use super::*;
 
-/// # Upright
-/// Upright (non-italic) font style in math.
-///
-/// ## Example
-/// ```
-/// $ upright(A) != A $
-/// ```
-///
-/// ## Parameters
-/// - body: Content (positional, required)
-///   The piece of formula to style.
-///
-/// ## Category
-/// math
-#[func]
-#[capable(LayoutMath)]
-#[derive(Debug, Hash)]
-pub struct UprightNode(pub Content);
-
-#[node]
-impl UprightNode {
-    fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
-        Ok(Self(args.expect("body")?).pack())
-    }
-}
-
-impl LayoutMath for UprightNode {
-    fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> {
-        ctx.style(ctx.style.with_italic(false));
-        self.0.layout_math(ctx)?;
-        ctx.unstyle();
-        Ok(())
-    }
-}
-
 /// # Bold
 /// Bold font style in math.
 ///
@@ -70,10 +35,45 @@ impl LayoutMath for BoldNode {
     }
 }
 
+/// # Upright
+/// Upright (non-italic) font style in math.
+///
+/// ## Example
+/// ```
+/// $ upright(A) != A $
+/// ```
+///
+/// ## Parameters
+/// - body: Content (positional, required)
+///   The piece of formula to style.
+///
+/// ## Category
+/// math
+#[func]
+#[capable(LayoutMath)]
+#[derive(Debug, Hash)]
+pub struct UprightNode(pub Content);
+
+#[node]
+impl UprightNode {
+    fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
+        Ok(Self(args.expect("body")?).pack())
+    }
+}
+
+impl LayoutMath for UprightNode {
+    fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> {
+        ctx.style(ctx.style.with_italic(false));
+        self.0.layout_math(ctx)?;
+        ctx.unstyle();
+        Ok(())
+    }
+}
+
 /// # Italic
 /// Italic font style in math.
 ///
-/// This is already the default.
+/// For roman letters and greek lowercase letters, this is already the default.
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
@@ -278,7 +278,7 @@ impl LayoutMath for MonoNode {
 /// Blackboard bold (double-struck) font style in math.
 ///
 /// For uppercase latin letters, blackboard bold is additionally available
-/// through [symbols](/docs/reference/math/) of the form `NN` and `RR`.
+/// through [symbols](/docs/reference/math/symbols) of the form `NN` and `RR`.
 ///
 /// ## Example
 /// ```