diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs index e947d6175..3751292c4 100644 --- a/library/src/compute/data.rs +++ b/library/src/compute/data.rs @@ -14,7 +14,7 @@ use crate::prelude::*; /// /// ## Example /// ``` -/// #let results = csv("/data.csv") +/// #let results = csv("data.csv") /// /// #table( /// columns: 2, @@ -133,8 +133,8 @@ fn format_csv_error(error: csv::Error) -> String { /// °{day.unit} /// ] /// -/// #forecast(json("/monday.json")) -/// #forecast(json("/tuesday.json")) +/// #forecast(json("monday.json")) +/// #forecast(json("tuesday.json")) /// ``` /// /// ## Parameters @@ -180,7 +180,10 @@ fn convert_json(value: serde_json::Value) -> Value { /// Format the user-facing JSON error message. fn format_json_error(error: serde_json::Error) -> String { assert!(error.is_syntax() || error.is_eof()); - format!("failed to parse json file: syntax error in line {}", error.line()) + format!( + "failed to parse json file: syntax error in line {}", + error.line() + ) } /// # XML @@ -225,7 +228,7 @@ fn format_json_error(error: serde_json::Error) -> String { /// } /// } /// -/// #let file = xml("/example.xml") +/// #let file = xml("example.xml") /// #for child in file(0).children { /// if (type(child) == "dictionary") { /// article(child) diff --git a/library/src/compute/utility.rs b/library/src/compute/utility.rs index 1a3511d01..f8a6d4dc3 100644 --- a/library/src/compute/utility.rs +++ b/library/src/compute/utility.rs @@ -6,6 +6,20 @@ use crate::text::Case; /// # Blind Text /// Create blind text. /// +/// This function yields a Latin-like _Lorem Ipsum_ blind text with the given +/// number of words. The sequence of words generated by the function is always +/// the same but randomly chosen. As usual for blind texts, it does not make any +/// sense. Use it as a placeholder to try layouts. +/// +/// ## Example +/// ``` +/// = Blind Text +/// #lorem(30) +/// +/// = More Blind Text +/// #lorem(15) +/// ``` +/// /// ## Parameters /// - words: usize (positional, required) /// The length of the blind text in words. @@ -21,12 +35,41 @@ pub fn lorem(args: &mut Args) -> SourceResult { /// # Numbering /// Apply a numbering pattern to a sequence of numbers. /// +/// Numbering patterns are strings that define how a sequence of numbers should +/// be rendered as text. The patterns consist of [counting +/// symbols](#parameters--pattern) for which the actual number is substituted, +/// their prefixes, and one suffix. The prefixes and the suffix are repeated as-is. +/// +/// ## Example +/// ``` +/// #numbering("1.1)", 1, 2, 3) \ +/// #numbering("1.b.i", 1, 2) \ +/// #numbering("I – 1", 12, 2) +/// ``` +/// /// ## Parameters /// - pattern: NumberingPattern (positional, required) /// A string that defines how the numbering works. /// +/// **Counting symbols** are `1`, `a`, `A`, `i`, `I` and `*`. They are replaced +/// by the number in the sequence, in the given case. +/// +/// The `*` character means that symbols should be used to count, in the order +/// of `*`, `†`, `‡`, `§`, `¶`, and `‖`. If there are more than six items, the +/// number is represented using multiple symbols. +/// +/// **Suffixes** are all characters after the last counting symbol. They are +/// repeated as-is at the end of any rendered number. +/// +/// **Prefixes** are all characters that are neither counting symbols nor +/// suffixes. They are repeated as-is at in front of their rendered equivalent +/// of their counting symbol. +/// /// - numbers: NonZeroUsize (positional, variadic) -/// The numbers to apply the pattern to. +/// The numbers to apply the pattern to. Must be positive. +/// +/// If more numbers than counting symbols are given, the last counting symbol +/// with its prefix is repeated. /// /// ## Category /// utility @@ -96,7 +139,11 @@ impl FromStr for NumberingPattern { }; let prefix = pattern[handled..i].into(); - let case = if c.is_uppercase() { Case::Upper } else { Case::Lower }; + let case = if c.is_uppercase() { + Case::Upper + } else { + Case::Lower + }; pieces.push((prefix, kind, case)); handled = i + 1; } diff --git a/library/src/layout/align.rs b/library/src/layout/align.rs index 9fcb216f5..7e2693aa8 100644 --- a/library/src/layout/align.rs +++ b/library/src/layout/align.rs @@ -3,6 +3,16 @@ use crate::prelude::*; /// # Align /// Align content horizontally and vertically. /// +/// ## Example +/// ``` +/// #set align(center) +/// +/// Centered text, a sight to see \ +/// In perfect balance, visually \ +/// Not left nor right, it stands alone \ +/// A work of art, a visual throne +/// ``` +/// /// ## Parameters /// - body: Content (positional, required) /// The content to align. @@ -10,6 +20,27 @@ use crate::prelude::*; /// - alignment: Axes> (positional, settable) /// The alignment along both axes. /// +/// Horizontal alignments can be `left`, `center`, `right`, `start`, or `end`. +/// The `start` and `end` alignments are relative to the current +/// [text direction](@text). +/// +/// Vertical alignments can be `top`, `horizon`, or `bottom`. +/// +/// To align along both axes at the same time, add the two alignments using +/// the `+` operator to get a 2d alignment. For example, `top + right` aligns +/// the content to the top right corner. +/// +/// ### Example +/// ``` +/// #set text(lang: "ar") +/// +/// مثال +/// #align( +/// end + horizon, +/// rect(inset: 12pt)[ركن] +/// ) +/// ``` +/// /// ## Category /// layout #[func] diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs index e8ae5f35c..0b1433e0c 100644 --- a/library/src/layout/columns.rs +++ b/library/src/layout/columns.rs @@ -3,6 +3,34 @@ use crate::text::TextNode; /// # Columns /// Separate a region into multiple equally sized columns. +/// +/// The column function allows to separate the interior of any container into +/// multiple columns. It will not equalize the height of the columns, instead, +/// the columns will take up the height of their container or the remaining +/// height on the page. The columns function can break across pages if +/// necessary. +/// +/// ## Example +/// ``` +/// = [An extraordinarily +/// long heading] +/// +/// #box(height: 68pt, +/// columns(2, gutter: 11pt)[ +/// #set par(justify: true) +/// This research was funded by the +/// National Academy of Sciences. +/// NAoS provided support for field +/// tests and interviews with a +/// grant of up to USD 40.000 for a +/// period of 6 months. +/// ] +/// ) +/// +/// In recent years, deep learning has +/// increasingly been used to solve a +/// variety of problems. +/// ``` /// /// ## Parameters /// - count: usize (positional, required) @@ -114,7 +142,25 @@ impl Layout for ColumnsNode { } /// # Column Break -/// A column break. +/// A forced column break. +/// +/// ## Example +/// ``` +/// #set page(columns: 2) +/// Preliminary findings from our +/// ongoing research project have +/// revealed a hitherto unknown +/// phenomenon of extraordinary +/// significance. +/// +/// #colbreak() +/// Through rigorous experimentation +/// and analysis, we have discovered +/// a hitherto uncharacterized process +/// that defies our current +/// understanding of the fundamental +/// laws of nature. +/// ``` /// /// ## Parameters /// - weak: bool (named) diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs index 933deebac..62e129b46 100644 --- a/library/src/layout/container.rs +++ b/library/src/layout/container.rs @@ -5,6 +5,21 @@ use crate::prelude::*; /// # Box /// An inline-level container that sizes content. /// +/// Normally, all elements except inline math, text, and boxes are block-level +/// and cannot occur inside of a paragraph. The box element allows you to create +/// inline-level containers. Boxes take the size of their contents by default +/// but can also be sized explicitly. +/// +/// ## Example +/// ``` +/// Refer to the docs +/// #box( +/// height: 9pt, +/// image("docs.svg") +/// ) +/// for more information. +/// ``` +/// /// ## Parameters /// - body: Content (positional) /// The contents of the box. @@ -79,6 +94,24 @@ impl Inline for BoxNode {} /// # Block /// A block-level container that places content into a separate flow. /// +/// This can be used to force elements that would otherwise be inline to become +/// block-level. This is especially useful when writing `{show}` rules. +/// +/// ## Example +/// ``` +/// [ +/// #show heading: it => it.title +/// = No block +/// Some text +/// ] +/// +/// [ +/// #show heading: it => block(it.title) +/// = Block +/// Some more text +/// ] +/// ``` +/// /// ## Parameters /// - body: Content (positional) /// The contents of the block. @@ -87,11 +120,11 @@ impl Inline for BoxNode {} /// The spacing around this block. /// /// - above: Spacing (named, settable) -/// The spacing between the previous and this block. Takes precedence over +/// The spacing between this block and its predecessor. Takes precedence over /// `spacing`. /// /// - below: Spacing (named, settable) -/// The spacing between this block and the following one. Takes precedence +/// The spacing between this block and its successor. Takes precedence /// over `spacing`. /// /// ## Category @@ -110,6 +143,8 @@ impl BlockNode { #[property(skip)] pub const BELOW: VNode = VNode::block_spacing(Em::new(1.2).into()); /// Whether this block must stick to the following one. + /// + /// Use this to prevent page breaks between e.g. a heading and its body. #[property(skip)] pub const STICKY: bool = false; diff --git a/src/syntax/source.rs b/src/syntax/source.rs index 6144d5241..9b76af12a 100644 --- a/src/syntax/source.rs +++ b/src/syntax/source.rs @@ -124,8 +124,11 @@ impl Source { } // Recalculate the line starts after the edit. - self.lines - .extend(lines_from(start_byte, start_utf16, &self.text[start_byte..])); + self.lines.extend(lines_from( + start_byte, + start_utf16, + &self.text[start_byte..], + )); // Incrementally reparse the replaced range. let mut root = std::mem::take(&mut self.root).into_inner();