---
title: "Using boilerplate with Quarto for Scientific Writing"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using boilerplate with Quarto for Scientific Writing}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE  # Don't evaluate code in vignette building
)
```

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

## Introduction

The `boilerplate` package is designed to streamline scientific writing in Quarto documents. This vignette demonstrates a complete workflow for using `boilerplate` to manage reusable text templates in your research papers.

## Why Use boilerplate with Quarto?

Quarto is becoming the standard for reproducible scientific documents. The `boilerplate` package enhances Quarto workflows by:

- Centralizing reusable text in version-controlled databases
- Enabling consistent language across documents
- Supporting collaborative workflows
- Reducing errors through template reuse
- Facilitating updates when methods change
- Supporting both RDS and JSON formats for different use cases (see `vignette("boilerplate-json-workflow")`)

## Setting Up a Quarto Project

### Recommended Project Structure

```
my-research-project/
├── .boilerplate-data/          # boilerplate databases
├── manuscript/
│   ├── paper.qmd               # Main manuscript
│   ├── _methods.qmd            # Methods section
│   └── references.bib          # Bibliography (auto-copied)
└── .gitignore                  # Exclude backups
```

### Initialise boilerplate

```{r init}
# Use a project-specific directory
# For this example, using a temporary directory
data_path <- file.path(tempdir(), "quarto_example")

# Initialise all databases
boilerplate_init(
  data_path = data_path,
  create_dirs = TRUE,
  create_empty = FALSE,  # Load default content
  confirm = FALSE,
  quiet = TRUE
)
```

### Configure .gitignore

Add to your `.gitignore`:

```
# Exclude boilerplate backups
.boilerplate-data/*.bak
```

## Building Your Text Database

### Methods Templates

Create reusable methods templates with placeholders:

```{r methods-templates}
# Import database first
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Add participant recruitment template to the unified database
db <- boilerplate_add_entry(
  db,
  path = "methods.participants.recruitment",
  value = "We recruited {{n_participants}} participants through {{recruitment_method}}.",
  category = "methods"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)
```

### Measures Database

Store information about your measures:

```{r measures-templates}
# Add a measure to the unified database
db$measures$gad7 <- list(
  name = "GAD-7",
  description = "Generalized Anxiety Disorder 7-item scale",
  type = "ordinal",  # Required field
  items = list(
    "Feeling nervous, anxious, or on edge",
    "Not being able to stop or control worrying"
  ),
  reference = "@spitzer2006"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)
```

## Using Templates in Quarto

Here's how to use boilerplate in your Quarto document:

```{r quarto-example}
# Import database (using the temp path from above)
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Generate methods text
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants.recruitment",
  global_vars = list(
    n_participants = 250,
    recruitment_method = "online panels"
  ),
  db = db,
  quiet = TRUE
)

# Output: "We recruited 250 participants through online panels."
```

## Example Quarto Document Structure

Your main Quarto document (`paper.qmd`) might look like:

```yaml
---
title: "Your Research Paper"
author: "Your Name"
format: pdf
---
```

Then in the document:

```r
## Introduction

[Your introduction...]

## Methods

{{< include _methods.qmd >}}

## Results

[Your results...]
```

And in `_methods.qmd`:

```r
library(boilerplate)

# Load database and generate text
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Generate participant section
participant_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants.recruitment",
  global_vars = list(n_participants = 250),
  db = db
)

cat(participant_text)
```

## Best Practices

1. **Version Control**: Commit your `.boilerplate-data/*.rds` files to git
2. **Documentation**: Document template variables in descriptions
3. **Organization**: Use hierarchical paths (e.g., `methods.participants.recruitment`)
4. **Collaboration**: Share databases through version control
5. **Maintenance**: Use batch operations to update multiple entries

## Bibliography Management

The boilerplate package can manage your bibliography file, ensuring consistent citations across projects:

```{r bibliography-setup}
# Add bibliography information to your database
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Using the example bibliography included with the package
example_bib <- system.file("extdata", "example_references.bib", package = "boilerplate")
db <- boilerplate_add_bibliography(
  db,
  url = paste0("file://", example_bib),
  local_path = "references.bib"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)
```

### Automatic Bibliography Copying

When generating text, automatically copy the bibliography:

```{r bibliography-copy}
# Generate text and copy bibliography
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "statistical.default",  # Use existing section
  db = db,
  copy_bibliography = TRUE,
  bibliography_path = "manuscript/"  # Copy to manuscript directory
)
```

Your Quarto document header would include:

```yaml
---
title: "Your Paper"
bibliography: references.bib
---
```

### Validating Citations

Ensure all citations in your boilerplate text exist in your bibliography:

```{r validate-citations}
# Validate references
validation <- boilerplate_validate_references(db)

if (!validation$valid) {
  warning("Missing references: ", paste(validation$missing, collapse = ", "))
}
```

## Advanced Features

### Batch Updates

Update multiple entries at once:

```{r batch-ops}
# Update all methods entries
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

boilerplate_batch_edit(
  db = db$methods,
  field = "text",
  new_value = function(text) gsub("old text", "new text", text),
  target_entries = "*",
  preview = TRUE  # Preview changes first
)
```

### Quarto Parameters

Use Quarto parameters with boilerplate:

```yaml
---
params:
  n_participants: 250
  study_name: "Study 1"
---
```

Then in your code:

```{r params-example}
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants",
  global_vars = list(
    n_participants = params$n_participants,
    study_name = params$study_name
  ),
  db = db
)
```

## Conclusion

The `boilerplate` package enhances Quarto workflows by providing a robust system for managing reusable text templates. This approach ensures consistency, reduces errors, and streamlines the scientific writing process.