Improve documentation for page bleed

crates/typst-library/src/layout/page.rs

@@ -150,32 +150,33 @@ pub struct PageElem {
 
     /// The page's bleed margin.
     ///
-    /// The bleed is a part of the content that extends beyond the edge of the
+    /// The bleed is the area of content that extends beyond the final trimmed
-    /// final trimmed page. It ensures that there are no unprinted edges in the
+    /// size of the page. It ensures that no unprinted edges appear in the final
-    /// final product, even if there's a slight misalignment during trimming.
+    /// product, even if minor trimming misalignments occur.
     ///
-    /// - `{auto}`: The bleed is set to 0mm on each side.
+    /// Accepted values:
-    /// - A single length: The same bleed on all sides.
+    ///
-    /// - A dictionary: With a dictionary, the bleed can be set individually.
+    /// - `{auto}`: Sets the bleed to `0mm` on all sides.
-    ///   The dictionary can contain the following keys in order of precedence:
+    /// - A single length: Applies the same bleed to all sides.
-    ///   - `top`: The top bleed.
+    /// - A dictionary: Allows setting bleed values individually. The dictionary
-    ///   - `right`: The right bleed.
+    ///   may include the following keys, listed in order of precedence:
-    ///   - `bottom`: The bottom bleed.
+    ///   - `top`: Bleed at the top of the page.
-    ///   - `left`: The left bleed.
+    ///   - `right`: Bleed at the right side.
-    ///   - `inside`: The bleed at the inner side of the page (where the
+    ///   - `bottom`: Bleed at the bottom.
-    ///     [binding]($page.binding) is).
+    ///   - `left`: Bleed at the left side.
-    ///   - `outside`: The bleed at the outer side of the page (opposite to the
+    ///   - `inside`: Bleed on the inner side of the page (next to
     ///     [binding]($page.binding)).
-    ///   - `x`: The horizontal bleeds.
+    ///   - `outside`: Bleed on the outer side of the page (opposite the
-    ///   - `y`: The vertical bleeds.
+    ///     [binding]($page.binding)).
-    ///   - `rest`: The bleeds on all sides except those for which the
+    ///   - `x`: Horizontal bleed (applies to both left/right or inside/outside).
-    ///     dictionary explicitly sets a size.
+    ///   - `y`: Vertical bleed (applies to both top and bottom).
+    ///   - `rest`: Default bleed for any sides not explicitly set.
     ///
-    /// The values for `left` and `right` are mutually exclusive with
+    /// Note: The keys `left` and `right` are mutually exclusive with `inside` and
-    /// the values for `inside` and `outside`.
+    /// `outside`.
     ///
-    /// On PDF output, if bleed is different of zero, it sets a TrimBox and a
+    /// On PDF output, if the bleed is non-zero, a `TrimBox` and a `BleedBox` are
-    /// BleedBox for the page.
+    /// defined for the page.
     ///
     /// ```example
     /// #set page(