Split up and document shapes

6 files changed, 33 insertions, 30 deletions

diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs
index 5bff050b..8a772f2d 100644
--- a/library/src/layout/container.rs
+++ b/library/src/layout/container.rs
@@ -134,10 +134,14 @@ impl Inline for BoxNode {}
 ///   The spacing between this block and its predecessor. Takes precedence over
 ///   `spacing`.
 ///
+///   The default value is `{1.2em}`.
+///
 /// - below: Spacing (named, settable)
 ///   The spacing between this block and its successor. Takes precedence
 ///   over `spacing`.
 ///
+///   The default value is `{1.2em}`.
+///
 /// ## Category
 /// layout
 #[func]
diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs
index 00233cd1..a3ee5df7 100644
--- a/library/src/layout/grid.rs
+++ b/library/src/layout/grid.rs
@@ -7,28 +7,31 @@ use super::Spacing;
 ///
 /// The grid element allows you to arrange content in a grid. You can define the
 /// number of rows and columns, as well as the size of the gutters between them.
-/// There are multiple sizing modes for columns and rows, including fixed sizes,
-/// that can be used to create complex layouts.
+/// There are multiple sizing modes for columns and rows that can be used to
+/// create complex layouts.
 ///
 /// The sizing of the grid is determined by the track sizes specified in the
 /// arguments. Because each of the sizing parameters accepts the same values, we
-/// will explain them here. Each sizing argument accepts an array of track
-/// sizes. A track size is either:
+/// will explain them just once, here. Each sizing argument accepts an array of
+/// individual track sizes. A track size is either:
 ///
-/// - a fixed length (e.g. `{10pt}`). The track will be exactly this size.
-/// - `{auto}`. The track will be sized to fit its contents. It will be at most
+/// - `{auto}`: The track will be sized to fit its contents. It will be at most
 ///   as large as the remaining space. If there is more than one `{auto}` track
-///   which, together, claim more than the available space, the tracks will be
-///   resized to fit the available space.
-/// - a fractional length (e.g. `{1fr}`). Once all other tracks have been sized,
+///   which, and together they claim more than the available space, the `{auto}`
+///   tracks will fairly distribute the available space among themselves.
+///
+/// - A fixed or relative length (e.g. `{10pt}` or `{20% - 1cm}`): The track
+///   will be exactly of this size.
+///
+/// - A fractional length (e.g. `{1fr}`): Once all other tracks have been sized,
 ///   the remaining space will be divided among the fractional tracks according
-///   to their fraction. For example, if there are two fractional tracks, each
+///   to their fractions. For example, if there are two fractional tracks, each
 ///   with a fraction of `{1fr}`, they will each take up half of the remaining
 ///   space.
 ///
 /// To specify a single track, the array can be omitted in favor of a single
 /// value. To specify multiple `{auto}` tracks, enter the number of tracks
-/// instead of a value. For example, `columns:` `{3}` is equivalent to
+/// instead of an array. For example, `columns:` `{3}` is equivalent to
 /// `columns:` `{(auto, auto, auto)}`.
 ///
 /// ## Example
diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs
index a63a4974..01ae48c5 100644
--- a/library/src/layout/hide.rs
+++ b/library/src/layout/hide.rs
@@ -4,9 +4,9 @@ use crate::prelude::*;
 /// Hide content without affecting layout.
 ///
 /// The `hide` function allows you to hide content while the layout still 'sees'
-/// it. This is useful to create to create whitespace that is exactly as large
-/// as some content. It may also be useful to redact content because its
-/// arguments are not included in the output.
+/// it. This is useful to create whitespace that is exactly as large as some
+/// content. It may also be useful to redact content because its arguments are
+/// not included in the output.
 ///
 /// ## Example
 /// ```
diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs
index 43a7768e..c1ac6118 100644
--- a/library/src/layout/page.rs
+++ b/library/src/layout/page.rs
@@ -42,7 +42,7 @@ pub struct PageNode(pub Content);
 
 #[node]
 impl PageNode {
-    /// The unflipped width of the page.
+    /// The width of the page.
     ///
     /// # Example
     /// ```
@@ -58,7 +58,7 @@ impl PageNode {
     #[property(resolve)]
     pub const WIDTH: Smart<Length> = Smart::Custom(Paper::A4.width().into());
 
-    /// The unflipped height of the page.
+    /// The height of the page.
     ///
     /// If this is set to `{auto}`, page breaks can only be triggered manually
     /// by inserting a [page break](@pagebreak). Most examples throughout this
@@ -92,7 +92,6 @@ impl PageNode {
     ///
     /// - A single length: The same margin on all sides.
     /// - `{auto}`: The margin is set to the default value for the page's size.
-    /// - `{none}`: The page will be stripped of its margins.
     /// - A dictionary: With a dictionary, the margins can be set individually.
     ///   The dictionary can contain the following keys in order of precedence:
     ///   - `top`: The top margin.
@@ -101,7 +100,7 @@ impl PageNode {
     ///   - `left`: The left margin.
     ///   - `x`: The horizontal margins.
     ///   - `y`: The vertical margins.
-    ///   - `rest`: The margins on all sides except the sides for which the
+    ///   - `rest`: The margins on all sides except those for which the
     ///     dictionary explicitly sets a size.
     ///
     /// # Example
@@ -197,7 +196,7 @@ impl PageNode {
     ///       text(8pt, numbering("I", i))
     ///     )
     ///   )
-    ///   
+    ///
     ///   #lorem(18)
     /// ```
     #[property(referenced)]
diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs
index 39e040b3..3287df3a 100644
--- a/library/src/layout/stack.rs
+++ b/library/src/layout/stack.rs
@@ -13,7 +13,6 @@ use crate::prelude::*;
 /// ```
 /// #stack(
 ///   dir: ttb,
-///
 ///   rect(width: 40pt),
 ///   rect(width: 120pt),
 ///   rect(width: 90pt),
diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs
index 451656ae..c843ad4e 100644
--- a/library/src/layout/transform.rs
+++ b/library/src/layout/transform.rs
@@ -11,17 +11,15 @@ use crate::prelude::*;
 ///
 /// ## Example
 /// ```
-/// #rect(
-///   move(
-///     dx: 6pt, dy: 6pt,
-///     rect(
-///       inset: 8pt,
-///       fill: white,
-///       stroke: black,
-///       [Abra cadabra]
-///     )
+/// #rect(inset: 0pt, move(
+///   dx: 6pt, dy: 6pt,
+///   rect(
+///     inset: 8pt,
+///     fill: white,
+///     stroke: black,
+///     [Abra cadabra]
 ///   )
-/// )
+/// ))
 /// ```
 ///
 /// ## Parameters