glossary.Rmd

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

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

## Setup

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


## Definition File

Set the default path to the definition file.

```{r}
glossary_path("glossary.yml")
```

### Definition YAML File

You can store definitions in a YAML file. Use markdown to create paragraphs, links, and lists. Make sure each new line in a definition is indented two spaces (sorry YAML is a bit picky, but it's the best human-editable solution).

```
SESOI: |
  Smallest Effect Size of Interest: the smallest effect that is theoretically or practically meaningful

  See [Equivalence Testing for Psychological Research](https://doi.org/10.1177/2515245918770963) for a tutorial on methods for choosing an SESOI.
p-value: |
  The probability of the observed data, or more extreme data, if the null hypothesis is true. The lower the p-value, the higher the test statistic, and less likely it is to observe the data if the null hypothesis is true.
```

### Add Definitions with Code

Alternatively, you can add definitions to the file with code. You don't need to indent new lines if you add definitions this way.

```{r, eval = FALSE}
glossary_add(term = "power",
             def = "The probability of rejecting the null hypothesis when it is false, for a specific analysis, effect size, sample size, and criteria for significance."
")
```

### PsyTeachR Glossary

If you want to use the [PsyTeachR Glossary](https://psyteachr.github.io/glossary/), set the path to "psyteachr". This will produce links to the online glossary when you click on the term, so it's best to use with the "hover" popup type (see below).

```{r}
glossary_path("psyteachr")
glossary_popup("hover")
```

`r glossary("absolute path")`


```{r, echo = FALSE}
# reset for rest of page
glossary_path("glossary.yml")
```


## Popup Type

Set the popup type with `glossary_popup()`; options are "click" (default), "hover", and "none".

```{r}
glossary_popup("none")
```

`r glossary("alpha")`

```{r}
glossary_popup("hover")
```

`r glossary("alpha")`

```{r}
glossary_popup("click")
```

`r glossary("alpha")`

## Style

If your popup type is "click", you must add a style with the `glossary_style()` function for the popups to work. If you set the popup type to "hover", or "none", you can omit this and the in-text glossary terms will be styled like other links in your document.

Set the style at the top of your document (set the code chunk to `results='asis'`). The code below shows the default options.

```{r, results='asis'}
glossary_style(color = "purple", 
               text_decoration = "underline",
               def_bg = "#333",
               def_color = "white")
```

Alternatively, you can add your own CSS to your document (inline or in an external linked file) to create a more customised appearance. Just copy the text returned by the `glossary_style()` function and customise it.

```{r, eval = FALSE}
# append default styles to an external CSS file
write(glossary_style(), "glossary.css", append = TRUE)
```


## In-Text Terms

There are a few ways to customise the glossary term display.

* Look up a term from the glossary file with `glossary("alpha")`: `r glossary("alpha")`

* Display a different value for the term with `glossary("alpha", "$\\alpha$")`: `r glossary("alpha", "$\\alpha$")`

* Use an inline definition instead of the glossary file with `glossary("beta", def = "The second letter of the Greek alphabet")`: `r glossary("beta", def = "The second letter of the Greek alphabet")`

* Just show the term (no hover) with `glossary("effect size", show = "term")`: `r glossary("effect size", show = "term")`

* Just show the definition with `glossary("p-value", show = "def")`: `r glossary("p-value", show = "def")`

## Glossary Table

Show the table of terms defined on this page (or since the last reset) with `glossary_table()`:

```{r, echo = FALSE}
glossary_table()
```

You can reset the glossary table between sections with `glossary_reset()`.

## Quarto Books

Since quarto book chapters are each rendered in a new environment, you will need to load the glossary package for each chapter, and do any setup.

The function `add_to_quarto()` will set this up for you (this function is still experimental, so make sure you've committed a version of your project before using). If your working directory is the quarto project, run the following code to set it up. This will create and link a css file to setup popup styles, and create a demo glossary.yml file if you don't already have one. It will also add the required setup code to a file called _setup.R, and source this file in the .Rprofile for this project, so that it will run before each chapter in the book.

```{r, eval = FALSE}
add_to_quarto(quarto_dir = ".",
              css_path = "glossary.css",
              glossary_path = "glossary.yml",
              script_path = "_setup.R")
```

You can set up a book in another directory by changing the `quarto_dir` argument. Specify an existing `css_path` to append the popup styles to it. You can also specify an existing glossary path. Set `script_path` to `FALSE` to use a different method for pre-chapter setup. 

```{r, eval = FALSE}
add_to_quarto(quarto_dir = "~/mybook",
              css_path = "style.css",
              glossary_path = "my_glossary.yml",
              script_path = FALSE)
```

If you don't use the .Rprofile and _setup.R script method, you will need to start each chapter with a setup chunk that sets the appropriate defaults for your project.

```{r, eval = FALSE}
library(glossary)
glossary_path("my_glossary.yml")
glossary_persistent(TRUE)
```

Now, when you display the glossary table, it will show all items added since the last call to `glossary_reset()` in the project.