From 038f9b015ee1248c3636c5e1b2edb5c4767ed837 Mon Sep 17 00:00:00 2001 From: Laurenz Date: Wed, 21 Dec 2022 16:28:54 +0100 Subject: [PATCH] Document `line` function --- library/src/visualize/image.rs | 4 +-- library/src/visualize/line.rs | 47 ++++++++++++++++++++++++---------- library/src/visualize/shape.rs | 4 +-- tests/typ/visualize/line.typ | 36 +++++++++++++------------- 4 files changed, 55 insertions(+), 36 deletions(-) diff --git a/library/src/visualize/image.rs b/library/src/visualize/image.rs index 1744f389e..bbb545765 100644 --- a/library/src/visualize/image.rs +++ b/library/src/visualize/image.rs @@ -5,14 +5,14 @@ use typst::image::{Image, ImageFormat, RasterFormat, VectorFormat}; use crate::prelude::*; /// # Image -/// Show a raster or vector graphic. +/// A raster or vector graphic. /// /// Supported formats are PNG, JPEG, GIF and SVG. /// /// ## Example /// ``` /// #align(center)[ -/// #image("molecular.jpg", width: 2in) +/// #image("molecular.jpg", width: 80%) /// /// *A step in the molecular testing /// pipeline of our lab* diff --git a/library/src/visualize/line.rs b/library/src/visualize/line.rs index 7fed90ce7..188778426 100644 --- a/library/src/visualize/line.rs +++ b/library/src/visualize/line.rs @@ -1,22 +1,29 @@ use crate::prelude::*; /// # Line -/// Display a line without affecting the layout. +/// A line from one point to another. /// -/// You should only provide either an endpoint or an angle and a length. +/// ## Example +/// ``` +/// #set page(height: 100pt) +/// #line(end: (50%, 50%)) +/// ``` /// /// ## Parameters -/// - origin: Axes> (named) +/// - start: Axes> (named) /// The start point of the line. +/// Must be an array of exactly two relative lengths. /// -/// - to: Axes> (named) +/// - end: Axes> (named) /// The end point of the line. +/// Must be an array of exactly two relative lengths. /// /// - length: Rel (named) -/// The line's length. +/// The line's length. Mutually exclusive with `end`. /// /// - angle: Angle (named) -/// The angle at which the line points away from the origin. +/// The angle at which the line points away from the origin. Mutually +/// exclusive with `end`. /// /// ## Category /// visualize @@ -25,22 +32,34 @@ use crate::prelude::*; #[derive(Debug, Hash)] pub struct LineNode { /// Where the line starts. - pub origin: Axes>, - /// The offset from the `origin` where the line ends. + pub start: Axes>, + /// The offset from `start` where the line ends. pub delta: Axes>, } #[node] impl LineNode { - /// How to stroke the line. + /// How to stroke the line. This can be: + /// + /// - A length specifying the stroke's thickness. The color is inherited, + /// defaulting to black. + /// - A color to use for the stroke. The thickness is inherited, defaulting + /// to `{1pt}`. + /// - A stroke combined from color and thickness using the `+` operator as + /// in `{2pt + red}`. + /// + /// # Example + /// ``` + /// #line(length: 100%, stroke: 2pt + red) + /// ``` #[property(resolve, fold)] pub const STROKE: PartialStroke = PartialStroke::default(); fn construct(_: &Vm, args: &mut Args) -> SourceResult { - let origin = args.named("origin")?.unwrap_or_default(); + let start = args.named("start")?.unwrap_or_default(); - let delta = match args.named::>>("to")? { - Some(to) => to.zip(origin).map(|(to, from)| to - from), + let delta = match args.named::>>("end")? { + Some(end) => end.zip(start).map(|(to, from)| to - from), None => { let length = args.named::>("length")?.unwrap_or(Abs::cm(1.0).into()); @@ -53,7 +72,7 @@ impl LineNode { } }; - Ok(Self { origin, delta }.pack()) + Ok(Self { start, delta }.pack()) } } @@ -67,7 +86,7 @@ impl Layout for LineNode { let stroke = styles.get(Self::STROKE).unwrap_or_default(); let origin = self - .origin + .start .resolve(styles) .zip(regions.base) .map(|(l, b)| l.relative_to(b)); diff --git a/library/src/visualize/shape.rs b/library/src/visualize/shape.rs index 9bf2bbab5..2a733368b 100644 --- a/library/src/visualize/shape.rs +++ b/library/src/visualize/shape.rs @@ -205,7 +205,7 @@ impl Inline for RectNode {} /// ## Example /// ``` /// // Without content. -/// #square(size: 30pt) +/// #square(size: 40pt) /// /// // With content. /// #square[ @@ -428,7 +428,7 @@ impl Inline for EllipseNode {} /// ## Example /// ``` /// // Without content. -/// #circle(radius: 15pt) +/// #circle(radius: 25pt) /// /// // With content. /// #circle[ diff --git a/tests/typ/visualize/line.typ b/tests/typ/visualize/line.typ index 92490ef80..9cc9b8ccb 100644 --- a/tests/typ/visualize/line.typ +++ b/tests/typ/visualize/line.typ @@ -5,11 +5,11 @@ #line() --- -// Test the to argument. +// Test the `end` argument. { - line(to: (10pt, 0pt)) - line(origin: (0pt, 10pt), to: (0pt, 0pt)) - line(to: (15pt, 15pt)) + line(end: (10pt, 0pt)) + line(start: (0pt, 10pt), end: (0pt, 0pt)) + line(end: (15pt, 15pt)) } #v(.5cm) @@ -23,16 +23,16 @@ #set text(spacing: 0%) #set line(..args) #set align(left) - #line(length: +30%, origin: (09.0%, 02%)) - #line(length: +30%, origin: (38.7%, 02%), angle: -72deg) - #line(length: +30%, origin: (57.5%, 02%), angle: 252deg) - #line(length: +30%, origin: (57.3%, 02%)) - #line(length: -30%, origin: (88.0%, 02%), angle: -36deg) - #line(length: +30%, origin: (73.3%, 48%), angle: 252deg) - #line(length: -30%, origin: (73.5%, 48%), angle: 36deg) - #line(length: +30%, origin: (25.4%, 48%), angle: -36deg) - #line(length: +30%, origin: (25.6%, 48%), angle: -72deg) - #line(length: +32%, origin: (8.50%, 02%), angle: 34deg) + #line(length: +30%, start: (09.0%, 02%)) + #line(length: +30%, start: (38.7%, 02%), angle: -72deg) + #line(length: +30%, start: (57.5%, 02%), angle: 252deg) + #line(length: +30%, start: (57.3%, 02%)) + #line(length: -30%, start: (88.0%, 02%), angle: -36deg) + #line(length: +30%, start: (73.3%, 48%), angle: 252deg) + #line(length: -30%, start: (73.5%, 48%), angle: 36deg) + #line(length: +30%, start: (25.4%, 48%), angle: -36deg) + #line(length: +30%, start: (25.6%, 48%), angle: -72deg) + #line(length: +32%, start: (8.50%, 02%), angle: 34deg) ] #align(center, grid( @@ -44,9 +44,9 @@ --- // Test errors. -// Error: 11-18 point array must contain exactly two entries -#line(to: (50pt,)) +// Error: 12-19 point array must contain exactly two entries +#line(end: (50pt,)) --- -// Error: 15-27 expected relative length, found angle -#line(origin: (3deg, 10pt), length: 5cm) +// Error: 14-26 expected relative length, found angle +#line(start: (3deg, 10pt), length: 5cm)