From 10b17a04bc27a4b38a0534446d29151d4f6303b3 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Sun, 12 Feb 2023 22:39:20 +0100 Subject: [PATCH] Fix docs --- docs/src/reference/scripting.md | 2 +- docs/src/reference/types.md | 10 +++++----- library/src/compute/construct.rs | 2 +- library/src/compute/data.rs | 4 ++-- library/src/layout/container.rs | 24 +++++++++++++++--------- library/src/layout/place.rs | 17 +++++------------ library/src/layout/transform.rs | 31 ++++++++++++++----------------- library/src/meta/outline.rs | 13 +++++-------- library/src/text/raw.rs | 5 +++-- library/src/visualize/image.rs | 3 +-- library/src/visualize/line.rs | 1 + library/src/visualize/shape.rs | 6 +++--- 12 files changed, 56 insertions(+), 62 deletions(-) diff --git a/docs/src/reference/scripting.md b/docs/src/reference/scripting.md index 6928d22aa..68e73c62e 100644 --- a/docs/src/reference/scripting.md +++ b/docs/src/reference/scripting.md @@ -17,7 +17,7 @@ be interpreted as text, the expression can forcibly be ended with a semicolon (`;`). ```example -#rect[Hello] \ +#emph[Hello] \ #emoji.face \ #"hello".len() ``` diff --git a/docs/src/reference/types.md b/docs/src/reference/types.md index 744e1abd1..11580c8b3 100644 --- a/docs/src/reference/types.md +++ b/docs/src/reference/types.md @@ -76,8 +76,8 @@ Typst supports the following length units: ## Example ```example -#rect(width: 20pt) \ -#rect(width: 2em) \ +#rect(width: 20pt) +#rect(width: 2em) #rect(width: 1in) ``` @@ -797,10 +797,10 @@ arguments, arrays and dictionaries into a function call with the spread operator ## Example ```example #let format(title, ..authors) = [ - *{title}* \ - _Written by {authors + *#title* \ + _Written by #(authors .pos() - .join(", ", last: " and ")}._ + .join(", ", last: " and "));._ ] #format("ArtosFlow", "Jane", "Joe") diff --git a/library/src/compute/construct.rs b/library/src/compute/construct.rs index 2d450d5d2..f540d8288 100644 --- a/library/src/compute/construct.rs +++ b/library/src/compute/construct.rs @@ -90,7 +90,7 @@ castable! { /// ## Example /// ```example /// #for x in range(250, step: 50) { -/// square(fill: luma(x)) +/// box(square(fill: luma(x))) /// } /// ``` /// diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs index 305c66119..5c0d4e64c 100644 --- a/library/src/compute/data.rs +++ b/library/src/compute/data.rs @@ -151,7 +151,7 @@ fn format_csv_error(error: csv::Error) -> String { /// ## Example /// ```example /// #let forecast(day) = block[ -/// #square( +/// #box(square( /// width: 2cm, /// inset: 8pt, /// fill: if day.weather == "sunny" { @@ -163,7 +163,7 @@ fn format_csv_error(error: csv::Error) -> String { /// bottom + right, /// strong(day.weather), /// ), -/// ) +/// )) /// #h(6pt) /// #set text(22pt, baseline: -8pt) /// #day.temperature °#day.unit diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs index 930a27e71..49ce0372a 100644 --- a/library/src/layout/container.rs +++ b/library/src/layout/container.rs @@ -6,14 +6,9 @@ use crate::prelude::*; /// An inline-level container that sizes content. /// /// All elements except inline math, text, and boxes are block-level and cannot -/// occur inside of a paragraph. The box element is an inline-level container. -/// Boxes take the size of their contents by default but can also be sized -/// explicitly. -/// -/// _Note:_ While the behavior above will be the default in the future, the -/// transformation functions [`scale`]($func/scale), [`rotate`]($func/rotate), -/// and [`move`]($func/move) will currently yield inline nodes within -/// paragraphs. +/// occur inside of a paragraph. The box function can be used to integrate such +/// elements into a paragraph. Boxes take the size of their contents by default +/// but can also be sized explicitly. /// /// ## Example /// ```example @@ -29,9 +24,20 @@ use crate::prelude::*; /// - body: `Content` (positional) /// The contents of the box. /// -/// - width: `Rel` (named) +/// - width: `Sizing` (named) /// The width of the box. /// +/// Boxes can have [fractional]($type/fraction) widths, as the example +/// below demonstrates. +/// +/// _Note:_ Currently, only boxes and only their widths might be fractionally +/// sized within paragraphs. Support for fractionally sized images, shapes, +/// and more might be added in the future. +/// +/// ```example +/// Line in #box(width: 1fr, line(length: 100%)) between. +/// ``` +/// /// - height: `Rel` (named) /// The height of the box. /// diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs index c6e26b722..d5edaa797 100644 --- a/library/src/layout/place.rs +++ b/library/src/layout/place.rs @@ -37,18 +37,11 @@ use crate::prelude::*; /// 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] -/// } -/// } -/// ) +/// #set page(height: 100pt) +/// #for i in range(16) { +/// let amount = i * 4pt +/// place(center, dx: amount - 32pt, dy: amount)[A] +/// } /// ``` /// /// - dy: `Rel` (named) diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs index 5977e90b8..e0014ac07 100644 --- a/library/src/layout/transform.rs +++ b/library/src/layout/transform.rs @@ -26,10 +26,6 @@ use crate::prelude::*; /// - body: `Content` (positional, required) /// The content to move. /// -/// ```example -/// Hello, world!#move(dy: -2pt)[!]#move(dy: 2pt)[!] -/// ``` -/// /// - dx: `Rel` (named) /// The horizontal displacement of the content. /// @@ -92,11 +88,12 @@ impl Layout for MoveNode { /// /// ## Example /// ```example -/// #{ -/// range(16) -/// .map(i => rotate(24deg * i)[X]) -/// .join(h(1fr)) -/// } +/// #stack( +/// dir: ltr, +/// spacing: 1fr, +/// ..range(16) +/// .map(i => rotate(24deg * i)[X]), +/// ) /// ``` /// /// ## Parameters @@ -107,7 +104,7 @@ impl Layout for MoveNode { /// The amount of rotation. /// /// ```example -/// #rotate(angle: -1.571rad)[To space!] +/// #rotate(angle: -1.571rad)[Space!] /// ``` /// /// ## Category @@ -135,10 +132,10 @@ impl RotateNode { /// #set text(spacing: 8pt) /// #let square = square.with(width: 8pt) /// - /// #square() - /// #rotate(angle: 30deg, origin: center, square()) - /// #rotate(angle: 30deg, origin: top + left, square()) - /// #rotate(angle: 30deg, origin: bottom + right, square()) + /// #box(square()) + /// #box(rotate(angle: 30deg, origin: center, square())) + /// #box(rotate(angle: 30deg, origin: top + left, square())) + /// #box(rotate(angle: 30deg, origin: bottom + right, square())) /// ``` #[property(resolve)] pub const ORIGIN: Axes> = Axes::default(); @@ -188,7 +185,7 @@ impl Layout for RotateNode { /// ## Example /// ```example /// #set align(center) -/// #scale(x: -100%)[👍]👩‍🦱👍 +/// #scale(x: -100%)[This is mirrored.] /// ``` /// /// ## Parameters @@ -224,8 +221,8 @@ impl ScaleNode { /// By default, the origin is the center of the scaled element. /// /// ```example - /// A#scale(75%)[A]A \ - /// B#scale(75%, origin: bottom + left)[B]B + /// A#box(scale(75%)[A])A \ + /// B#box(scale(75%, origin: bottom + left)[B])B /// ``` #[property(resolve)] pub const ORIGIN: Axes> = Axes::default(); diff --git a/library/src/meta/outline.rs b/library/src/meta/outline.rs index d28a0f086..da2e1f00d 100644 --- a/library/src/meta/outline.rs +++ b/library/src/meta/outline.rs @@ -64,19 +64,16 @@ impl OutlineNode { /// ``` pub const INDENT: bool = false; - /// The symbol used to fill the space between the title and the page - /// number. Can be set to `none` to disable filling. The default is a - /// single dot. + /// Content to fill the space between the title and the page number. Can be + /// set to `none` to disable filling. The default is `{repeat[.]}`. /// /// ```example - /// #outline( - /// fill: pad(x: -1.5pt)[―] - /// ) + /// #outline(fill: line(length: 100%)) /// /// = A New Beginning /// ``` #[property(referenced)] - pub const FILL: Option = Some(TextNode::packed(".")); + pub const FILL: Option = Some(RepeatNode(TextNode::packed(".")).pack()); fn construct(_: &Vm, _: &mut Args) -> SourceResult { Ok(Self.pack()) @@ -184,7 +181,7 @@ impl Show for OutlineNode { seq.push(SpaceNode.pack()); seq.push( BoxNode { - body: RepeatNode(filler.clone()).pack(), + body: filler.clone(), width: Sizing::Fr(Fr::one()), height: Smart::Auto, baseline: Rel::zero(), diff --git a/library/src/text/raw.rs b/library/src/text/raw.rs index e87d82e90..d29cb7bf6 100644 --- a/library/src/text/raw.rs +++ b/library/src/text/raw.rs @@ -63,12 +63,13 @@ use crate::prelude::*; /// ````example /// // Display inline code in a small box /// // that retains the correct baseline. -/// #show raw.where(block: false): rect.with( +/// #show raw.where(block: false): it => box(rect( /// fill: luma(240), /// inset: (x: 3pt, y: 0pt), /// outset: (y: 3pt), /// radius: 2pt, -/// ) +/// it, +/// )) /// /// // Display block code in a larger box /// // with more padding. diff --git a/library/src/visualize/image.rs b/library/src/visualize/image.rs index 3a6eb3b08..5e3c7f83e 100644 --- a/library/src/visualize/image.rs +++ b/library/src/visualize/image.rs @@ -13,9 +13,8 @@ use crate::prelude::*; /// ```example /// #align(center)[ /// #image("molecular.jpg", width: 80%) -/// /// *A step in the molecular testing -/// pipeline of our lab* +/// pipeline of our lab* /// ] /// ``` /// diff --git a/library/src/visualize/line.rs b/library/src/visualize/line.rs index 890373ee6..553e06c88 100644 --- a/library/src/visualize/line.rs +++ b/library/src/visualize/line.rs @@ -6,6 +6,7 @@ use crate::prelude::*; /// ## Example /// ```example /// #set page(height: 100pt) +/// #line(length: 100%) /// #line(end: (50%, 50%)) /// ``` /// diff --git a/library/src/visualize/shape.rs b/library/src/visualize/shape.rs index 81309f935..61b8afdb2 100644 --- a/library/src/visualize/shape.rs +++ b/library/src/visualize/shape.rs @@ -133,7 +133,7 @@ impl RectNode { /// current [text edges]($func/text.top-edge). /// /// ```example - /// A #rect(inset: 0pt)[tight] fit. + /// A #box(rect(inset: 0pt)[tight]) fit. /// ``` #[property(resolve, fold)] pub const INSET: Sides>> = Sides::splat(Abs::pt(5.0).into()); @@ -147,12 +147,12 @@ impl RectNode { /// /// ```example /// This - /// #rect( + /// #box(rect( /// fill: luma(235), /// inset: (x: 3pt, y: 0pt), /// outset: (y: 3pt), /// radius: 2pt, - /// )[rectangle] + /// )[rectangle]) /// is inline. /// ``` #[property(resolve, fold)]