From c06be6699096535ee6658eda7ce84ea7f428b096 Mon Sep 17 00:00:00 2001 From: Martin Haug Date: Wed, 21 Dec 2022 13:16:59 +0100 Subject: [PATCH] Finish the layout docs --- library/src/layout/par.rs | 71 +++++++++++++++++++++++++++++++++++++ library/src/layout/place.rs | 39 ++++++++++++++++++++ library/src/layout/stack.rs | 16 ++++++++- 3 files changed, 125 insertions(+), 1 deletion(-) diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs index c05ed2e8e..25372bb67 100644 --- a/library/src/layout/par.rs +++ b/library/src/layout/par.rs @@ -14,6 +14,27 @@ use crate::text::{ /// # Paragraph /// Arrange text, spacing and inline-level nodes into a paragraph. /// +/// Although this function is primarily used in set rules to affect paragraph +/// properties, it can also be used to explicitly render its argument onto a +/// paragraph of its own. +/// +/// ## Example +/// ``` +/// #set par(indent: 1em, justify: true) +/// #show par: set block(spacing: 0.65em) +/// +/// We proceed by contradiction. +/// Suppose that there exists a set +/// of positive integers $a$, $b$, and +/// $c$ that satisfies the equation +/// $a^n + b^n = c^n$ for some +/// integer value of $n > 2$. +/// +/// Without loss of generality, +/// let a be the smallest of the +/// three integers. Then, we ... +/// ``` +/// /// ## Parameters /// - body: Content (positional, required) /// The contents of the paragraph. @@ -28,14 +49,57 @@ pub struct ParNode(pub StyleVec); #[node] impl ParNode { /// The indent the first line of a consecutive paragraph should have. + /// + /// The first paragraph on a page will never be indented. + /// + /// By typographic convention, paragraph breaks are indicated by either some + /// space between paragraphs or indented first lines. Consider turning the + /// [paragraph spacing](@block/spacing) off when using this property (e.g. + /// using `[#show par: set block(spacing: 0pt)]`). #[property(resolve)] pub const INDENT: Length = Length::zero(); + /// The spacing between lines. + /// + /// The default value is `{0.65em}`. #[property(resolve)] pub const LEADING: Length = Em::new(0.65).into(); + /// Whether to justify text in its line. + /// + /// Hyphenation will be enabled for justified paragraphs if the [text + /// property hyphenate](@text/hyphenate) is set to `{auto}` and the current + /// language is known. + /// + /// Note that the current [alignment](@align) still has an effect on the + /// placement of the last line except if it ends with a [justified line + /// break](@linebreak/justify). pub const JUSTIFY: bool = false; + /// How to determine line breaks. + /// + /// When this property is set to `{auto}`, its default value, optimized line + /// breaks will be used for justified paragraphs. Enabling optimized line + /// breaks for ragged paragraphs may also be worthwhile to improve the + /// appearance of the text. + /// + /// # Example + /// ``` + /// #set page(width: 190pt) + /// #set par(linebreaks: "simple") + /// Some texts are frustratingly + /// challenging to break in a + /// visually pleasing way. This + /// very aesthetic example is one + /// of them. + /// + /// #set par(linebreaks: "optimized") + /// Some texts are frustratingly + /// challenging to break in a + /// visually pleasing way. This + /// very aesthetic example is one + /// of them. + /// ``` pub const LINEBREAKS: Smart = Smart::Auto; fn construct(_: &Vm, args: &mut Args) -> SourceResult { @@ -145,6 +209,9 @@ castable! { /// Determine the linebreaks in a simple first-fit style. "simple" => Self::Simple, /// Optimize the linebreaks for the whole paragraph. + /// + /// Typst will try to produce more evenly filled lines of text by + /// considering the whole paragraph when calculating line breaks. "optimized" => Self::Optimized, } @@ -155,6 +222,10 @@ castable! { /// [for loops](/docs/reference/concepts#for-loop). Multiple consecutive /// paragraph breaks collapse into a single one. /// +/// ## Syntax +/// Instead of calling this function, you can insert two empty lines in your +/// markup to create a paragraph break. +/// /// ## Example /// ``` /// #for i in range(3) { diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs index 406aa862e..26ab7b183 100644 --- a/library/src/layout/place.rs +++ b/library/src/layout/place.rs @@ -3,16 +3,55 @@ use crate::prelude::*; /// # Place /// Place content at an absolute position. /// +/// Placed content will not affect the position of other content. Place is +/// always relative to its parent container and will be in the foreground of all +/// other content in the container. Page margins will be respected. +/// +/// +/// ## Example +/// ``` +/// #set page(height: 60pt) +/// Hello, world! +/// +/// #place( +/// top + right, +/// square( +/// width: 10pt, +/// stroke: 1pt + blue +/// ), +/// ) +/// ``` +/// /// ## Parameters /// - alignment: Axes> (positional) /// Relative to which position in the parent container to place the content. /// +/// When an axis of the page is `{auto}` sized, all alignments relative to that +/// axis will be ignored, instead, the item will be placed in the origin of the +/// axis. +/// /// - body: Content (positional, required) /// The content to place. /// /// - dx: Rel (named) /// The horizontal displacement of the placed content. /// +/// ### Example +/// ``` +/// #set align(center) +/// +/// #box( +/// width: 80pt, +/// height: 80pt, +/// { +/// for i in range(18) { +/// let amount = i * 4pt +/// place(dx: amount, dy: amount)[A] +/// } +/// } +/// ) +/// ``` +/// /// - dy: Rel (named) /// The vertical displacement of the placed content. /// diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs index c423b1a3a..39e040b3f 100644 --- a/library/src/layout/stack.rs +++ b/library/src/layout/stack.rs @@ -4,7 +4,21 @@ use super::{AlignNode, Spacing}; use crate::prelude::*; /// # Stack -/// Arrange content and spacing along an axis. +/// Arrange content and spacing horizontally or vertically. +/// +/// The stack places a list of items along an axis, with optional spacing +/// between each item. +/// +/// ## Example +/// ``` +/// #stack( +/// dir: ttb, +/// +/// rect(width: 40pt), +/// rect(width: 120pt), +/// rect(width: 90pt), +/// ) +/// ``` /// /// ## Parameters /// - items: StackChild (positional, variadic)