Rename place scope "page" to "parent" (#5027)

crates/typst/src/layout/columns.rs

@@ -28,14 +28,14 @@ use crate::layout::{
 ///
 /// # Breaking out of columns { #breaking-out }
 /// To temporarily break out of columns (e.g. for a paper's title), use
-/// page-scoped floating placement:
+/// parent-scoped floating placement:
 ///
 /// ```example:single
 /// #set page(columns: 2, height: 150pt)
 ///
 /// #place(
 ///   top + center,
-///   scope: "page",
+///   scope: "parent",
 ///   float: true,
 ///   text(1.4em, weight: "bold")[
 ///     My document

crates/typst/src/layout/flow/collect.rs

@@ -239,10 +239,10 @@ impl<'a> Collector<'a, '_, '_> {
             _ => {}
         }
 
-        if !float && scope == PlacementScope::Page {
+        if !float && scope == PlacementScope::Parent {
             bail!(
                 elem.span(),
-                "page-scoped positioning is currently only available for floating placement";
+                "parent-scoped positioning is currently only available for floating placement";
                 hint: "you can enable floating placement with `place(float: true, ..)`"
             );
         }

crates/typst/src/layout/flow/compose.rs

@@ -77,7 +77,7 @@ impl<'a, 'b> Composer<'a, 'b, '_, '_> {
     /// Lay out a container/page region, including container/page insertions.
     fn page(mut self, locator: Locator, regions: Regions) -> SourceResult<Frame> {
         // This loop can restart region layout when requested to do so by a
-        // `Stop`. This happens when there is a page-scoped float.
+        // `Stop`. This happens when there is a parent-scoped float.
         let checkpoint = self.work.clone();
         let output = loop {
             // Shrink the available space by the space used by page
@@ -89,7 +89,7 @@ impl<'a, 'b> Composer<'a, 'b, '_, '_> {
                 Ok(frame) => break frame,
                 Err(Stop::Finish(_)) => unreachable!(),
                 Err(Stop::Relayout(PlacementScope::Column)) => unreachable!(),
-                Err(Stop::Relayout(PlacementScope::Page)) => {
+                Err(Stop::Relayout(PlacementScope::Parent)) => {
                     *self.work = checkpoint.clone();
                     continue;
                 }
@@ -257,7 +257,7 @@ impl<'a, 'b> Composer<'a, 'b, '_, '_> {
         // Determine the base size of the chosen scope.
         let base = match placed.scope {
             PlacementScope::Column => regions.base(),
-            PlacementScope::Page => self.page_base,
+            PlacementScope::Parent => self.page_base,
         };
 
         // Lay out the placed element.
@@ -267,7 +267,7 @@ impl<'a, 'b> Composer<'a, 'b, '_, '_> {
         // placement, but only an approximation for page placement.
         let remaining = match placed.scope {
             PlacementScope::Column => regions.size.y,
-            PlacementScope::Page => {
+            PlacementScope::Parent => {
                 let remaining: Abs = regions
                     .iter()
                     .map(|size| size.y)
@@ -309,7 +309,7 @@ impl<'a, 'b> Composer<'a, 'b, '_, '_> {
         // Select the insertion area where we'll put this float.
         let area = match placed.scope {
             PlacementScope::Column => &mut self.column_insertions,
-            PlacementScope::Page => &mut self.page_insertions,
+            PlacementScope::Parent => &mut self.page_insertions,
         };
 
         // Put the float there.

crates/typst/src/layout/flow/mod.rs

@@ -60,7 +60,7 @@ pub fn layout_fragment(
 /// Lays out content into regions with columns.
 ///
 /// This is different from just laying out into column-sized regions as the
-/// columns can interact due to page-scoped placed elements.
+/// columns can interact due to parent-scoped placed elements.
 pub fn layout_fragment_with_columns(
     engine: &mut Engine,
     content: &Content,

crates/typst/src/layout/place.rs

@@ -37,23 +37,23 @@ pub struct PlaceElem {
 
     /// Relative to which containing scope something is placed.
     ///
-    /// Page-scoped floating placement is primarily used with figures and, for
+    /// The parent scope is primarily used with figures and, for
     /// this reason, the figure function has a mirrored [`scope`
     /// parameter]($figure.scope). Nonetheless, it can also be more generally
     /// useful to break out of the columns. A typical example would be to
     /// [create a single-column title section]($guides/page-setup/#columns) in a
     /// two-column document.
     ///
-    /// Note that page-scoped placement is currently only supported if `float`
+    /// Note that parent-scoped placement is currently only supported if `float`
     /// is `{true}`. This may change in the future.
     pub scope: PlacementScope,
 
     /// Whether the placed element has floating layout.
     ///
-    /// Floating elements are positioned at the top or bottom of the page,
-    /// displacing in-flow content. They are always placed in the in-flow
-    /// order relative to each other, as well as before any content following
-    /// a later [`place.flush`] element.
+    /// Floating elements are positioned at the top or bottom of the parent
+    /// container, displacing in-flow content. They are always placed in the
+    /// in-flow order relative to each other, as well as before any content
+    /// following a later [`place.flush`] element.
     ///
     /// ```example
     /// #set page(height: 150pt)
@@ -119,8 +119,8 @@ pub enum PlacementScope {
     /// Place into the current column.
     #[default]
     Column,
-    /// Place relative to the page, letting the content span over all columns.
-    Page,
+    /// Place relative to the parent, letting the content span over all columns.
+    Parent,
 }
 
 /// Asks the layout algorithm to place pending floating elements before

crates/typst/src/model/figure.rs

@@ -135,7 +135,7 @@ pub struct FigureElem {
 
     /// Relative to which containing scope something is placed.
     ///
-    /// Set this to `{"page"}` to create a full-width figure in a two-column
+    /// Set this to `{"parent"}` to create a full-width figure in a two-column
     /// document.
     ///
     /// Has no effect if `placement` is `{none}`.

docs/guides/page-setup.md

@@ -406,7 +406,7 @@ the `gutter` parameter.
 Very commonly, scientific papers have a single-column title and abstract, while
 the main body is set in two-columns. To achieve this effect, Typst's [`place`
 function]($place) can temporarily escape the two-column layout by specifying
-`{float: true}` and `{scope: "page"}`:
+`{float: true}` and `{scope: "parent"}`:
 
 ```example:single
 >>> #set page(height: 180pt)
@@ -416,7 +416,7 @@ function]($place) can temporarily escape the two-column layout by specifying
 #place(
   top + center,
   float: true,
-  scope: "page",
+  scope: "parent",
   text(1.4em, weight: "bold")[
     Impacts of Odobenidae
   ],

tests/suite/layout/flow/footnote.typ

@@ -84,7 +84,7 @@ Beautiful footnotes. #footnote[Wonderful, aren't they?]
 #place(
   top + center,
   float: true,
-  scope: "page",
+  scope: "parent",
   clearance: 12pt,
   strong[Title],
 )

tests/suite/layout/flow/place.typ

@@ -110,7 +110,7 @@ A
 #align(center)[A]
 #pagebreak()
 #align(center)[B]
-#place(bottom, scope: "page", rect(height: 10pt))
+#place(bottom, scope: "parent", rect(height: 10pt))
 
 --- place-float-flow-size-alone ---
 #set page(width: auto, height: auto)
@@ -123,7 +123,7 @@ A
 #set rect(width: 70%)
 
 #place(top + center, rect[I])
-#place(bottom + center, scope: "page", rect[II])
+#place(bottom + center, scope: "parent", rect[II])
 
 A
 #v(1fr)
@@ -137,7 +137,7 @@ C
 #set place(float: true, clearance: 10pt)
 #set rect(width: 70%)
 
-#place(top + center, scope: "page", rect[I])
+#place(top + center, scope: "parent", rect[I])
 #place(top + center, rect[II])
 
 // This test result is not ideal: The first column takes 30% of the full page,
@@ -200,19 +200,19 @@ C
 #set place(float: true, clearance: 10pt)
 #set rect(width: 70%)
 
-#place(top + center, scope: "page", rect[I])
+#place(top + center, scope: "parent", rect[I])
 #place(top + center, rect[II])
 #lines(4)
 #place(top + center, rect[III])
 #block(width: 100%, height: 70pt, fill: conifer)
-#place(bottom + center, scope: "page", rect[IV])
+#place(bottom + center, scope: "parent", rect[IV])
 #place(bottom + center, rect[V])
 #v(1pt, weak: true)
 #block(width: 100%, height: 60pt, fill: aqua)
 
 --- place-float-twocolumn-queued ---
 #set page(height: 100pt, columns: 2)
-#set place(float: true, scope: "page", clearance: 10pt)
+#set place(float: true, scope: "parent", clearance: 10pt)
 #let t(align, fill) = place(top + align, rect(fill: fill, height: 25pt))
 
 #t(left, aqua)
@@ -225,9 +225,9 @@ C
 #set place(float: true, clearance: 10pt)
 #set rect(width: 70%)
 
-#place(auto, scope: "page", rect[I]) // Should end up `top`
+#place(auto, scope: "parent", rect[I]) // Should end up `top`
 #lines(4)
-#place(auto, scope: "page", rect[II])  // Should end up `bottom`
+#place(auto, scope: "parent", rect[II])  // Should end up `bottom`
 #lines(4)
 
 --- place-float-twocolumn-fits ---
@@ -236,7 +236,7 @@ C
 #set rect(width: 70%)
 
 #lines(6)
-#place(auto, scope: "page", rect[I])
+#place(auto, scope: "parent", rect[I])
 #lines(12, "1")
 
 --- place-float-twocolumn-fits-not ---
@@ -245,7 +245,7 @@ C
 #set rect(width: 70%)
 
 #lines(10)
-#place(auto, scope: "page", rect[I])
+#place(auto, scope: "parent", rect[I])
 #lines(10, "1")
 
 --- place-float-threecolumn ---
@@ -253,9 +253,9 @@ C
 #set place(float: true, clearance: 10pt)
 #set rect(width: 70%)
 
-#place(bottom + center, scope: "page", rect[I])
+#place(bottom + center, scope: "parent", rect[I])
 #lines(21)
-#place(top + center, scope: "page", rect[II])
+#place(top + center, scope: "parent", rect[II])
 
 --- place-float-threecolumn-block-backlog ---
 #set page(height: 100pt, columns: 3)
@@ -264,10 +264,10 @@ C
 
 // The most important part of this test is that we get the backlog of the
 // conifer (green) block right.
-#place(top + center, scope: "page", rect[I])
+#place(top + center, scope: "parent", rect[I])
 #block(fill: aqua, width: 100%, height: 70pt)
 #block(fill: conifer, width: 100%, height: 160pt)
-#place(bottom + center, scope: "page", rect[II])
+#place(bottom + center, scope: "parent", rect[II])
 #place(top, rect(height: 40%)[III])
 #block(fill: yellow, width: 100%, height: 60pt)
 
@@ -296,7 +296,7 @@ C
 #t(top, 3)
 #colbreak()
 #cd
-#t(scope: "page", bottom, 11)
+#t(scope: "parent", bottom, 11)
 #colbreak()
 #cd
 #t(top, 12)

tests/suite/model/figure.typ

@@ -49,7 +49,7 @@ We can clearly see that @fig-cylinder and
 
 #figure(
   placement: auto,
-  scope: "page",
+  scope: "parent",
   caption: [I],
   rect(height: 15pt, width: 80%),
 )
@@ -70,7 +70,7 @@ We can clearly see that @fig-cylinder and
 
 #figure(
   placement: auto,
-  scope: "page",
+  scope: "parent",
   caption: [IV],
   rect(width: 80%),
 )