# Using boilerplate with Quarto for Scientific Writing

    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

    # 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:

    # 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:

    # 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:

    # 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:

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

Then in the document:

    ## Introduction

    [Your introduction...]

    ## Methods

    {{< include _methods.qmd >}}

    ## Results

    [Your results...]

And in `_methods.qmd`:

    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:

    # 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:

    # 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:

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

### Validating Citations

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

    # 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:

    # 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:

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

Then in your code:

    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.