From 15cd273c82a96128a63781981a4405fcd2b1e846 Mon Sep 17 00:00:00 2001
From: Martin Haug <mhaug@live.de>
Date: Tue, 20 Dec 2022 23:39:27 +0100
Subject: [PATCH] Document spacing and breaks

---
 library/src/layout/columns.rs |  4 +++
 library/src/layout/page.rs    | 13 +++++++
 library/src/layout/par.rs     | 13 +++++++
 library/src/layout/spacing.rs | 66 +++++++++++++++++++++++++++++++++--
 4 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs
index 0b1433e0c..c03ff433b 100644
--- a/library/src/layout/columns.rs
+++ b/library/src/layout/columns.rs
@@ -144,6 +144,10 @@ impl Layout for ColumnsNode {
 /// # Column Break
 /// A forced column break.
 /// 
+/// The function will behave like a [page break](@pagebreak) when used in a
+/// single column layout or the last column on a page. Otherwise, content after
+/// the column break will be placed in the next column.
+/// 
 /// ## Example
 /// ```
 /// #set page(columns: 2)
diff --git a/library/src/layout/page.rs b/library/src/layout/page.rs
index dfaaae23a..105638a7e 100644
--- a/library/src/layout/page.rs
+++ b/library/src/layout/page.rs
@@ -158,6 +158,19 @@ impl Debug for PageNode {
 /// # Page Break
 /// A page break.
 ///
+/// A manually forced page break. It must not be used inside any containers.
+///
+/// ## Example
+/// ```
+/// The next page contains
+/// more details on compound theory.
+/// #pagebreak()
+///
+/// // Examples only render the first
+/// // page, so this is not visible.
+/// == Compound Theory
+/// ```
+///
 /// ## Parameters
 /// - weak: bool (named)
 ///   If true, the page break is skipped if the current page is already empty.
diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs
index bdd8c9d5b..f966d30be 100644
--- a/library/src/layout/par.rs
+++ b/library/src/layout/par.rs
@@ -151,6 +151,19 @@ castable! {
 /// # Paragraph Break
 /// A paragraph break.
 ///
+/// This starts a new paragraph. Especially useful when used within code like
+/// [for loops](/docs/reference/concepts#for-loop). Paragraph breaks in an empty
+/// paragraph are ignored.
+///
+/// ## Example
+/// ```
+/// #for i in range(3) {
+///   [Blind text #i: ]
+///   lorem(5)
+///   parbreak()
+/// }
+/// ```
+///
 /// ## Category
 /// layout
 #[func]
diff --git a/library/src/layout/spacing.rs b/library/src/layout/spacing.rs
index f306d47c2..91b36661d 100644
--- a/library/src/layout/spacing.rs
+++ b/library/src/layout/spacing.rs
@@ -3,7 +3,20 @@ use std::cmp::Ordering;
 use crate::prelude::*;
 
 /// # Spacing (H)
-/// Horizontal spacing in a paragraph.
+/// Insert horizontal spacing into a paragraph.
+/// 
+/// The spacing can be a length or a `fractional`. In the latter case, the
+/// remaining space on the line is distributed among all fractional spacings
+/// according to their relative size.
+/// 
+/// ## Example
+/// ```
+/// #circle(fill: red)
+/// #h(1fr)
+/// #circle(fill: yellow)
+/// #h(2fr)
+/// #circle(fill: green)
+/// ```
 ///
 /// ## Parameters
 /// - amount: Spacing (positional, required)
@@ -13,6 +26,18 @@ use crate::prelude::*;
 ///   If true, the spacing collapses at the start or end of a paragraph.
 ///   Moreover, from multiple adjacent weak spacings all but the largest one
 ///   collapse.
+/// 
+///   ### Example
+///   ```
+///   #h(1cm, weak: true)
+///   We identified a group of
+///   _weak_ specimens that fail to
+///   manifest in most cases. However,
+///   when #h(8pt, weak: true)
+///   supported
+///   #h(8pt, weak: true) on all
+///   sides, they do show up.
+///   ```
 ///
 /// ## Category
 /// layout
@@ -65,8 +90,30 @@ impl Behave for HNode {
 }
 
 /// # Spacing (V)
-/// Vertical spacing.
+/// Insert vertical spacing.
+/// 
+/// The spacing can be a length or a `fractional`. In the latter case, the
+/// remaining space on the page is distributed among all fractional spacings
+/// according to their relative size.
 ///
+/// ## Example
+/// ```
+/// In this report, we will explore
+/// the various ethical
+/// considerations that must be
+/// taken into account when
+/// conducting psychological
+/// research: 
+/// #v(5mm)
+/// 
+/// - Informed consent
+///
+/// - Participant confidentiality
+///
+/// - The use of
+///   vulnerable populations.
+/// ```
+/// 
 /// ## Parameters
 /// - amount: Spacing (positional, required)
 ///   How much spacing to insert.
@@ -75,7 +122,20 @@ impl Behave for HNode {
 ///   If true, the spacing collapses at the start or end of a flow.
 ///   Moreover, from multiple adjacent weak spacings all but the largest one
 ///   collapse.
-///
+///   
+///   ### Example
+///   ```
+///   Only paragraph spacing
+/// 
+///   Override paragraph spacing
+///     with weak space
+///     #v(7mm, weak: true)
+/// 
+///   Add to paragraph spacing
+///     #v(7mm, weak: false)
+/// 
+///   A secret, fourth thing
+///  ```
 /// ## Category
 /// layout
 #[func]