@@ -89,6 +89,16 @@ impl Show for LocateElem {
8989/// In the future, the provided styles might also be directly accessed to look
9090/// up styles defined by [set rules]($styling/#set-rules).
9191///
92+ /// ```example
93+ /// #let thing(body) = style(styles => {
94+ /// let size = measure(body, styles)
95+ /// [Width of "#body" is #size.width]
96+ /// })
97+ ///
98+ /// #thing[Hey] \
99+ /// #thing[Welcome]
100+ /// ```
101+ ///
92102/// Display: Style
93103/// Category: meta
94104/// Returns: content
@@ -122,67 +132,61 @@ impl Show for StyleElem {
122132 }
123133}
124134
125- /// Provides access to the current outer container's (or page's, if none) size (width and height).
126- ///
127- /// The given function must accept a single parameter, `size`, which is a dictionary with keys
128- /// `width` and `height`, both having the type [`length`]($type/length).
129- ///
130- /// That is, if this `layout` call is done inside (for example) a box of size 800pt (width)
131- /// by 400pt (height), then the specified function will be given the parameter
132- /// `(width: 800pt, height: 400pt)`.
133- ///
134- /// If, however, this `layout` call is placed directly on the page, not inside any container,
135- /// then the function will be given `(width: page_width, height: page_height)`, where `page_width`
136- /// and `page_height` correspond to the current page's respective dimensions, minus its margins.
137- ///
138- /// This is useful, for example, to convert a [`ratio`]($type/ratio) value (such as `5%`, `100%`
139- /// etc.), which are usually based upon the outer container's dimensions (precisely what this
140- /// function gives), to a fixed length (in `pt`).
141- ///
142- /// This is also useful if you're trying to make content fit a certain box, and doing certain
143- /// arithmetic using `pt` (for example, comparing different lengths) is required.
135+ /// Provides access to the current outer container's (or page's, if none) size
136+ /// (width and height).
144137///
145- /// Please note: This function may provide a width or height of `infpt` if one of the page
146- /// dimensions is `auto`, under certain circumstances. This should not normally occur for
147- /// usual page sizes, however .
138+ /// The given function must accept a single parameter, `size`, which is a
139+ /// dictionary with keys `width` and `height`, both of type
140+ /// [`length`]($type/length) .
148141///
142+
149143/// ```example
150- /// layout(size => {
151- /// // work with the width and height of the container we're in
152- /// // using size.width and size.height
153- /// })
144+ /// #let text = lorem(30)
145+ /// #layout(size => style(styles => [
146+ /// #let (height,) = measure(
147+ /// block(width: size.width, text),
148+ /// styles,
149+ /// )
150+ /// This text is #height high with
151+ /// the current page width: \
152+ /// #text
153+ /// ]))
154+ /// ```
154155///
155- /// layout(size => {
156- /// // convert 49% (of page width) to 'pt'
157- /// // note that "ratio" values are always relative to a certain, possibly arbitrary length,
158- /// // but it's usually the current container's width or height (e.g., for table columns,
159- /// // 15% would be relative to the width, but, for rows, it would be relative to the height).
160- /// let percentage_of_width = (49% / 1%) * 0.01 * size.width
161- /// // ... use the converted value ...
162- /// })
156+ /// If the `layout` call is placed inside of a box width a width of `{800pt}`
157+ /// and a height of `{400pt}`, then the specified function will be given the
158+ /// parameter `{(width: 800pt, height: 400pt)}`. If it placed directly into the
159+ /// page it receives the page's dimensions minus its margins. This is mostly
160+ /// useful in combination with [measurement]($func/measure).
163161///
164- /// // The following two boxes are equivalent, and will have rectangles sized 200pt and 40pt:
162+ /// You can also use this function to resolve [`ratio`]($type/ratio) to fixed
163+ /// lengths. This might come in handy if you're building your own layout
164+ /// abstractions.
165165///
166- /// #box(width: 200pt, height: 40pt, {
167- /// rect(width: 100%, height: 100%)
166+ /// ```example
167+ /// #layout(size => {
168+ /// let half = 50% * size.width
169+ /// [Half a page is #half wide.]
168170/// })
169- ///
170- /// #box(width: 200pt, height: 40pt, layout(size => {
171- /// rect(width: size.width, height: size.height)
172- /// }))
173171/// ```
174172///
173+ /// Note that this function will provide an infinite width or height if one of
174+ /// the page width or height is `auto`, respectively.
175+ ///
175176/// Display: Layout
176177/// Category: meta
177178/// Returns: content
178179#[ func]
179180pub fn layout (
180- /// A function to call with the outer container's size. Its return value is displayed
181- /// in the document.
181+ /// A function to call with the outer container's size. Its return value is
182+ /// displayed in the document.
183+ ///
184+ /// The container's size is given as a [dictionary]($type/dictionary) with
185+ /// the keys `width` and `height`.
182186///
183187/// This function is called once for each time the content returned by
184188/// `layout` appears in the document. That makes it possible to generate
185- /// content that depends on the size of the container it is inside.
189+ /// content that depends on the size of the container it is inside of .
186190func : Func ,
187191) -> Value {
188192 LayoutElem :: new ( func) . pack ( ) . into ( )
0 commit comments