Improved ratio and relative length docs (#5750)

Co-authored-by: PgBiel <9021226+PgBiel@users.noreply.github.com>
Co-authored-by: Laurenz <laurmaedje@gmail.com>

2 files changed, 71 insertions, 10 deletions

diff --git a/crates/typst-library/src/layout/ratio.rs b/crates/typst-library/src/layout/ratio.rs
index 1c0dcd29..cf826c2b 100644
--- a/crates/typst-library/src/layout/ratio.rs
+++ b/crates/typst-library/src/layout/ratio.rs
@@ -8,15 +8,35 @@ use crate::foundations::{repr, ty, Repr};
 
 /// A ratio of a whole.
 ///
-/// Written as a number, followed by a percent sign.
+/// A ratio is written as a number, followed by a percent sign. Ratios most
+/// often appear as part of a [relative length]($relative), to specify the size
+/// of some layout element relative to the page or some container.
 ///
-/// # Example
 /// ```example
-/// #set align(center)
-/// #scale(x: 150%)[
-///   Scaled apart.
-/// ]
+/// #rect(width: 25%)
 /// ```
+///
+/// However, they can also describe any other property that is relative to some
+/// base, e.g. an amount of [horizontal scaling]($scale.x) or the
+/// [height of parentheses]($math.lr.size) relative to the height of the content
+/// they enclose.
+///
+/// # Scripting
+/// Within your own code, you can use ratios as you like. You can multiply them
+/// with various other types as shown below:
+///
+/// |  Multiply by    |  Example                | Result          |
+/// |-----------------|-------------------------|-----------------|
+/// | [`ratio`]       | `{27% * 10%}`           | `{2.7%}`        |
+/// | [`length`]      | `{27% * 100pt}`         | `{27pt}`        |
+/// | [`relative`]    | `{27% * (10% + 100pt)}` | `{2.7% + 27pt}` |
+/// | [`angle`]       | `{27% * 100deg}`        | `{27deg}`       |
+/// | [`int`]         | `{27% * 2}`             | `{54%}`         |
+/// | [`float`]       | `{27% * 0.37037}`       | `{10%}`         |
+/// | [`fraction`]    | `{27% * 3fr}`           | `{0.81fr}`      |
+///
+/// When ratios are displayed in the document, they are rounded to two
+/// significant digits for readability.
 #[ty(cast)]
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct Ratio(Scalar);
diff --git a/crates/typst-library/src/layout/rel.rs b/crates/typst-library/src/layout/rel.rs
index 76d73678..7fe5d9c0 100644
--- a/crates/typst-library/src/layout/rel.rs
+++ b/crates/typst-library/src/layout/rel.rs
@@ -14,17 +14,58 @@ use crate::layout::{Abs, Em, Length, Ratio};
 /// addition and subtraction of a length and a ratio. Wherever a relative length
 /// is expected, you can also use a bare length or ratio.
 ///
-/// # Example
+/// # Relative to the page
+/// A common use case is setting the width or height of a layout element (e.g.,
+/// [block], [rect], etc.) as a certain percentage of the width of the page.
+/// Here, the rectangle's width is set to `{25%}`, so it takes up one fourth of
+/// the page's _inner_ width (the width minus margins).
+///
 /// ```example
-/// #rect(width: 100% - 50pt)
+/// #rect(width: 25%)
+/// ```
 ///
-/// #(100% - 50pt).length \
-/// #(100% - 50pt).ratio
+/// Bare lengths or ratios are always valid where relative lengths are expected,
+/// but the two can also be freely mixed:
+/// ```example
+/// #rect(width: 25% + 1cm)
 /// ```
 ///
+/// If you're trying to size an element so that it takes up the page's _full_
+/// width, you have a few options (this highly depends on your exact use case):
+///
+/// 1. Set page margins to `{0pt}` (`[#set page(margin: 0pt)]`)
+/// 2. Multiply the ratio by the known full page width (`{21cm * 69%}`)
+/// 3. Use padding which will negate the margins (`[#pad(x: -2.5cm, ...)]`)
+/// 4. Use the page [background](page.background) or
+///    [foreground](page.foreground) field as those don't take margins into
+///    account (note that it will render the content outside of the document
+///    flow, see [place] to control the content position)
+///
+/// # Relative to a container
+/// When a layout element (e.g. a [rect]) is nested in another layout container
+/// (e.g. a [block]) instead of being a direct descendant of the page, relative
+/// widths become relative to the container:
+///
+/// ```example
+/// #block(
+///   width: 100pt,
+///   fill: aqua,
+///   rect(width: 50%),
+/// )
+/// ```
+///
+/// # Scripting
+/// You can multiply relative lengths by [ratios]($ratio), [integers]($int), and
+/// [floats]($float).
+///
 /// A relative length has the following fields:
 /// - `length`: Its length component.
 /// - `ratio`: Its ratio component.
+///
+/// ```example
+/// #(100% - 50pt).length \
+/// #(100% - 50pt).ratio
+/// ```
 #[ty(cast, name = "relative", title = "Relative Length")]
 #[derive(Default, Copy, Clone, Eq, PartialEq, Hash)]
 pub struct Rel<T: Numeric = Length> {