---
title: "Quarto reports"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quarto reports}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(ezrsurvey)
```

Building a deck from R suits a deliverable whose shape you already know. A
report you will rewrite between waves, or one that has to go out as a web page
this quarter and a PDF the next, wants a document you can edit rather than a
script that emits one. `scaffold_report()` writes that document: a Quarto file
already wired to your data, with the analysis in it, ready to render.

Everything below writes into a temporary folder.

```{r}
report_dir <- tempdir()
```

## The scaffold

Pick the output format and you get a `.qmd` set up for it.

```{r}
path <- scaffold_report(
  "html",
  path = file.path(report_dir, "survey-report.qmd"),
  title = "Q2 Customer Survey",
  author = "Research team",
  overwrite = TRUE
)

file.exists(path)
```

Four formats are supported, and the difference between them is the YAML header
and the chunk settings, not the analysis:

```r
scaffold_report("html", path = "report.qmd")   # a web page
scaffold_report("pdf", path = "report.qmd")    # print
scaffold_report("docx", path = "report.qmd")   # a Word document to be edited further
scaffold_report("pptx", path = "report.qmd")   # slides
```

What the file contains is a working report rather than an empty skeleton:
setup, the data read in, a respondent profile, the headline measures, a driver
model, a chart or two and a precision appendix, with placeholder narrative
between them saying what each section is for.

```{r}
writeLines(head(readLines(path), 25))
```

## Rendering it

Rendering needs Quarto itself, which is not an R package:

```r
quarto::quarto_render("survey-report.qmd")
```

The scaffold takes the data file as a parameter, so the same report runs
against the next wave without being edited:

```r
quarto::quarto_render("survey-report.qmd", execute_params = list(data = "wave-3.csv"))
```

From the command line that is `-P data:wave-3.csv`.

## On your own template

The pptx and docx scaffolds accept a reference document, which is how the
report inherits your organisation's look:

```r
scaffold_report("pptx", path = "report.qmd", title = "Q2 Customer Survey",
                reference_doc = "brand/org-template.pptx")
```

With `use_brand()` already set, the template it carries is used by default and
the argument can be left out.

> Quarto's `reference-doc` requires the standard layout names ("Title Slide",
> "Title and Content" and so on). If your organisation's template renamed its
> layouts, Quarto will not find them; build that deck with `report_deck()`
> instead, which reads placeholders rather than names. See
> [PowerPoint decks](powerpoint-decks.html).

## A finished example to copy

The scaffold is a starting point. For a complete worked report on the bundled
data, with every chart type, real narrative rather than placeholders, and the
matching deck script beside it:

```{r}
example_dir <- file.path(report_dir, "ezrsurvey-example")
example_report(example_dir, overwrite = TRUE)

list.files(example_dir)
```

Copy that into a project and adapt it. It is the fastest way to see how the
pieces fit together in a document rather than one call at a time.

## Which route to take

| You want | Use |
| --- | --- |
| A deck from a list of charts, no shape to control | `report_deck()` |
| A deck with chapters, commentary and mixed slides | `report_new()` and the `report_*` builders |
| A document you will edit and re-render each wave | `scaffold_report()` |
| The same analysis as html, pdf, docx and pptx | `scaffold_report()`, one per format |
| A worked example to learn from | `example_report()` |