Record a section's layout for assembly

Specifies how one section should be composed and placed when the document is rendered, writing that layout into the document begun by initialize_doc(). This is the middle of the assembly chain: it records intent — the patchwork syntax, the inner and outer designs, whether to show the title and description — without rendering anything. Rendering happens later, all at once, in generate_docs().

Usage

layout_section(
  .doc,
  section,
  .patchwork_syntax = NULL,
  .inner_design = NULL,
  .outer_design = "A",
  add_title = TRUE,
  add_desc = TRUE,
  meta_pt_sizes = c(24, 16),
  txt_size = 6,
  height = NULL,
  width = NULL
)

Arguments

.doc: A document object from initialize_doc().
section: The id of the section to lay out. Must exist in the document.
.patchwork_syntax: Patchwork syntax composing the section's content slots — sec_txt, sec_tbl, sec_fig — e.g. sec_txt + sec_fig. Written unquoted; captured as code.
.inner_design: Optional patchwork design string arranging the content slots (the inner layout). Applies when .patchwork_syntax uses no positional operators (|, /). NULL (default) leaves arrangement to the syntax.
.outer_design: Patchwork design string placing the composed section on the page (the outer layout); defaults to "A" (full-bleed).
add_title, add_desc: Whether to show the section's title and description when rendered (default TRUE for both).
meta_pt_sizes: Point sizes for the title and description, as a length-2 numeric (default c(24, 16)).
txt_size: Point sizes for a textual section (if any). Defaults to 6.
height, width: Optional per-section canvas dimensions in inches. In development: reserved for a future pile backend that renders each section as an independent file. Ignored when the document is rendered as a single uniform deck. NULL (default) uses the document canvas.

Value

The document object, with this section's layout recorded. Returned so layout_section() calls can be chained.

Details

layout_section() is chainable: pipe one call into the next to lay out each section in turn, building the document's structure as a readable sequence of calls.

Layout settings left NULL are recorded as missing, so that generate_docs() can fall through to the document-level defaults set in initialize_doc(). This cascade — section setting if given, document default otherwise — lets most sections inherit a consistent look while individual sections override what they need.

A section must be laid out before it can be rendered; generate_docs() will report any section that was added to the document but never passed through layout_section().

Inner and outer layout

Each section has two layouts, the same distinction used in preview_section(). The inner layout (.patchwork_syntax with .inner_design) arranges the section's own content — sec_txt, sec_tbl, sec_fig — into a composition. The outer layout (.outer_design) places that composition onto the page, full-bleed ("A", the default) or in a region with reserved space (e.g. "#AA").

The layout recorded here is applied to every subsection of the section when the document is generated, so a section fanned out into many subsections is composed consistently across all of them.

Examples

if (FALSE) { # \dontrun{
doc <-
  report |>
  initialize_doc() |>
  layout_section(
    "estimates",
    .patchwork_syntax = sec_txt + sec_fig,
    .inner_design     = "AABB"
  ) |>
  layout_section(
    "robustness",
    .patchwork_syntax = sec_tbl,
    add_desc          = FALSE
  )
} # }