diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs index eb45cfbea..85d464b12 100644 --- a/library/src/layout/grid.rs +++ b/library/src/layout/grid.rs @@ -5,19 +5,83 @@ use super::Spacing; /// # Grid /// Arrange content in a grid. /// +/// The grid element allows you to arrange content in a grid. You can define the +/// number of rows and columns, as well as the size of the gutters between them. +/// There are multiple sizing modes for columns and rows, including fixed sizes, +/// that can be used to create complex layouts. +/// +/// The sizing of the grid is determined by the track sizes specified in the +/// arguments. Because each of the sizing parameters accepts the same values, we +/// will explain them here: +/// +/// Each sizing argument accepts an array of track sizes. A track size is either +/// - a fixed length (e.g. `10pt`). The track will be exactly this size. +/// - `{auto}`. The track will be sized to fit its contents. It will be at most +/// as large as the remaining space. If there is more than one `auto` track +/// that, together, claim more than the available space, they will be resized +/// to fit the available space. +/// - a `fractional` length (e.g. `{1fr}`). Once all other tracks have been +/// sized, the remaining space will be divided among the fractional tracks +/// according to their fraction. For example, if there are two fractional +/// tracks, each with a fraction of `1`, they will each take up half of the +/// remaining space. +/// +/// To specify a single track, the array can be omitted in favor of a single +/// value. To specify multiple `{auto}` tracks, enter the number of tracks +/// instead of a value. For example, `columns: {3}` is equivalent to +/// `columns: {(auto, auto, auto)}`. +/// +/// ## Example +/// ``` +/// #set text(hyphenate: true) +/// #let cell = rect.with( +/// inset: 6pt, +/// fill: rgb("e4e5ea"), +/// width: 100%, +/// radius: 6pt +/// ) +/// +/// #grid( +/// columns: (60pt, 1fr, 60pt), +/// rows: (60pt, auto), +/// gutter: 3pt, +/// cell(height: 100%)[*Easy to learn*], +/// cell(height: 100%)[Great output], +/// cell(height: 100%)[*Intuitive*], +/// cell[*Our best Typst yet*], +/// cell[ +/// Responsive design in print +/// for everyone +/// ], +/// cell[*One more thing...*], +/// ) +/// ``` +/// /// ## Parameters /// - cells: Content (positional, variadic) /// The contents of the table cells. /// +/// The cells are populated in row-major order. +/// /// - rows: TrackSizings (named) /// Defines the row sizes. /// +/// If there are more cells than fit the defined rows, the last row is +/// repeated until there are no more cells. +/// /// - columns: TrackSizings (named) /// Defines the column sizes. /// +/// Either specify a track size array or provide an +/// integer to create a grid with that many `{auto}`-sized columns. Note that +/// opposed to rows and gutters, providing a single track size will only ever +/// create a single column. +/// /// - gutter: TrackSizings (named) /// Defines the gaps between rows & columns. /// +/// If there are more gutters than defined sizes, the last gutter is repeated. +/// /// - column-gutter: TrackSizings (named) /// Defines the gaps between columns. Takes precedence over `gutter`. /// diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs index f7f195492..dec6dd1cb 100644 --- a/library/src/layout/hide.rs +++ b/library/src/layout/hide.rs @@ -3,6 +3,17 @@ use crate::prelude::*; /// # Hide /// Hide content without affecting layout. /// +/// The `hide` function allows you to hide content while the layout still 'sees' +/// it. This is useful to create layout items that are exactly as large as some +/// content. It may also be useful to redact content because its arguments are +/// not included in the output. +/// +/// ## Example +/// ``` +/// Hello Jane \ +/// #hide[Hello] Joe +/// ``` +/// /// ## Parameters /// - body: Content (positional, required) /// The content to hide. diff --git a/library/src/layout/pad.rs b/library/src/layout/pad.rs index 7825d133e..13b573bfc 100644 --- a/library/src/layout/pad.rs +++ b/library/src/layout/pad.rs @@ -1,7 +1,20 @@ use crate::prelude::*; /// # Padding -/// Pad content at the sides. +/// Add spacing around content. +/// +/// The `pad` function adds spacing around content. The spacing can be specified +/// for each side individually, or for all sides at once by specifying a +/// positional argument. +/// +/// ## Example +/// ``` +/// #set align(center) +/// +/// #pad(16pt, image("typing.jpg")) +/// _Typing speeds can be +/// measured in words per minute._ +/// ``` /// /// ## Parameters /// - body: Content (positional, required) diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs index 6d2caf1d2..92a317808 100644 --- a/library/src/layout/transform.rs +++ b/library/src/layout/transform.rs @@ -5,10 +5,33 @@ use crate::prelude::*; /// # Move /// Move content without affecting layout. /// +/// The `move` function allows you to hide content while the layout still 'sees' +/// it at the original positions. Containers will still be sized as if the content +/// was not moved. +/// +/// ## Example +/// ``` +/// #rect( +/// move( +/// dx: 6pt, dy: 6pt, +/// rect( +/// inset: 8pt, +/// fill: white, +/// stroke: black, +/// [Abra cadabra] +/// ) +/// ) +/// ) +/// ``` +/// /// ## Parameters /// - 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. /// @@ -62,6 +85,19 @@ impl Inline for MoveNode {} /// # Rotate /// Rotate content with affecting layout. /// +/// Rotate an element by a given angle. The layout will act as if the element +/// was not rotated. +/// +/// ## Example +/// ``` +/// { +/// range(16) +/// .map(i => +/// rotate(360deg / 15 * i)[X] +/// ).join(h(1fr)) +/// } +/// ``` +/// /// ## Parameters /// - body: Content (positional, required) /// The content to rotate. @@ -121,6 +157,16 @@ impl Inline for RotateNode {} /// # Scale /// Scale content without affecting layout. /// +/// The `scale` function allows you to scale and mirror content without +/// affecting the layout. +/// +/// +/// ## Example +/// ``` +/// #set align(center) +/// #scale(x: -100%)[👍]👩‍🦱👍 +/// ``` +/// /// ## Parameters /// - body: Content (positional, required) /// The content to scale. @@ -128,9 +174,13 @@ impl Inline for RotateNode {} /// - x: Ratio (named) /// The horizontal scaling factor. /// +/// The body will be mirrored horizontally if the parameter is negative. +/// /// - y: Ratio (named) /// The vertical scaling factor. /// +/// The body will be mirrored vertically if the parameter is negative. +/// /// ## Category /// layout #[func]