From 196d9594fbb88985dbf61c146a82b8299bb5fd2e Mon Sep 17 00:00:00 2001 From: Laurenz Date: Sun, 29 Jan 2023 23:15:00 +0100 Subject: [PATCH] Math documentation improvements --- library/src/math/accent.rs | 29 ++++++++------- library/src/math/lr.rs | 2 +- library/src/math/matrix.rs | 30 ++++++++++++++-- library/src/math/op.rs | 2 +- library/src/math/style.rs | 74 +++++++++++++++++++------------------- 5 files changed, 82 insertions(+), 55 deletions(-) diff --git a/library/src/math/accent.rs b/library/src/math/accent.rs index fdb59c5c8..9183b93bf 100644 --- a/library/src/math/accent.rs +++ b/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` | ` | +/// | 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 diff --git a/library/src/math/lr.rs b/library/src/math/lr.rs index 2eb567b9d..cdd5718c7 100644 --- a/library/src/math/lr.rs +++ b/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 diff --git a/library/src/math/matrix.rs b/library/src/math/matrix.rs index 9a0900bfb..6aa7ba77c 100644 --- a/library/src/math/matrix.rs +++ b/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", /// ) $ /// ``` diff --git a/library/src/math/op.rs b/library/src/math/op.rs index 766d63819..5665a6371 100644 --- a/library/src/math/op.rs +++ b/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 diff --git a/library/src/math/style.rs b/library/src/math/style.rs index 14f97ae8a..c45a8d936 100644 --- a/library/src/math/style.rs +++ b/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 { - 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 { + 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 /// ```