From 2c251d42fe5873fd3bb81e32fe01a9134a6c50db Mon Sep 17 00:00:00 2001
From: Andrew Voynov <andrewvoynov.b@gmail.com>
Date: Fri, 24 Jan 2025 22:53:06 +0300
Subject: [PATCH] docs: improved ratio and relative length docs

Co-authored-by: PgBiel <9021226+PgBiel@users.noreply.github.com>
---
 crates/typst-library/src/layout/ratio.rs | 42 +++++++++++++++++++++++-
 crates/typst-library/src/layout/rel.rs   |  2 ++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/crates/typst-library/src/layout/ratio.rs b/crates/typst-library/src/layout/ratio.rs
index 1c0dcd298..069a7b3ba 100644
--- a/crates/typst-library/src/layout/ratio.rs
+++ b/crates/typst-library/src/layout/ratio.rs
@@ -8,7 +8,47 @@ use crate::foundations::{repr, ty, Repr};
 
 /// A ratio of a whole.
 ///
-/// Written as a number, followed by a percent sign.
+/// Written as a number, followed by a percent sign. A common use case is
+/// setting the width or height of a container (e.g., [block], [rect], etc.),
+/// thus it is used as a part of a [relative length](relative) (because
+/// internally containers use relative length for width and height fields):
+///
+/// ```example
+/// #block(width: 240pt, {
+///   rect(width: 25%, layout(size => size.width))
+/// })
+/// ```
+///
+/// Here the block width is set to `{250pt}` (just to demonstrate the use of
+/// ratio with containers), and inside of it the rectangle width is set to
+/// `{25%}`, which means "get 25% of the width of the innermost container" (240
+/// ⋅ 0.25 = 60). The reason it shows `{50pt}` instead of `{60pt}` is due to
+/// the default value of inset. If we set it to `{0pt}`, then we will get
+/// the expected result (although the number will be cramped):
+///
+/// ```example
+/// #block(width: 240pt, {
+///   rect(width: 25%, inset: 0pt, layout(size => size.width))
+/// })
+/// ```
+///
+/// If you are trying to use the page width/height's value as the base for the
+/// ratio, then the value is equal to the width/height of the page minus the
+/// margins (left and right for width, top and bottom for height). To force
+/// Typst to use the full length 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 by a full length value (`{21cm * 69%}`)
+/// 3. use padding which will negate the margins (`#pad(x: -2.5cm, ...)`)
+/// 4. use page [background](page.background)/[foreground](page.foreground)
+///    field that doesn't use the margins (note that it will render the content
+///    outside of the document flow, see [place] to control the content
+///    position)
+///
+/// However, within your own code, you can use ratios as you'd like. You can
+/// multiply ratio by ratio, [length], [relative length](relative), [angle],
+/// [int], [float], and [fraction].
 ///
 /// # Example
 /// ```example
diff --git a/crates/typst-library/src/layout/rel.rs b/crates/typst-library/src/layout/rel.rs
index 76d736785..bc986b88f 100644
--- a/crates/typst-library/src/layout/rel.rs
+++ b/crates/typst-library/src/layout/rel.rs
@@ -14,6 +14,8 @@ 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.
 ///
+/// You can multiply relative length by [ratio], [int], and [float].
+///
 /// # Example
 /// ```example
 /// #rect(width: 100% - 50pt)