instructions.qmd

# How to Use this Book {#sec-instructions}

```{r, include = FALSE}
source("R/booktem_setup.R")
source("R/my_setup.R")
```


## Setup {#sec-setup}

### Install booktem

``` r
# install.packages("devtools")
devtools::install_github("debruine/booktem")
```

### Quarto Options

The file `_quarto.yml` contains various options that you can set to change the format and look of your book.

#### Language Options

There is some default text for things like the "authors" list and "table of contents" that might need translations. Set the `lang` key to the 2-letter language code for your language.

You can make a [custom translation](https://quarto.org/docs/authoring/language.html#custom-translations) by translating the values in the `include/_language.yml` file. 

``` yaml
lang: en
# language: include/_language.yml
```

#### Project Options

The `project` key defines the inputs and outputs for the book ([quarto reference](https://quarto.org/docs/reference/projects/books.html#project)).

::: {.callout-note collapse="true"}
## project key

``` yaml
project:
  type: book
  output-dir: docs
  resources: resources 
```
:::

The `output-dir` key defines the directory where the rendered web files will be saved. This is set to `docs` in order to be compatible with [GitHub Pages](https://pages.github.com/), but you can change this if you are working with a different repository that expects the web files to be in a different directory.

The `resources` key specifies a directory that is copied verbatim to the output directory. This is where you should put, for example, data files that you want to make accessible online (sometimes they don't automatically copy over when linked).

#### Book Options

The `book` key defines options that affect the look and function of the book ([quarto reference](https://quarto.org/docs/reference/projects/books.html#section)).

::: {.callout-note collapse="true"}
## book key

``` yaml
book:
  title: Book
  subtitle: ~
  author: ~
  doi: ~
  license: CC-BY 4.0
  description: ~
  cover-image: images/logos/logo.png
  image: images/logos/logo.png
  favicon: images/logos/logo.png
  cookie-consent: false
  google-analytics: ~
  page-navigation: true
  search: true
  # comments:
  #   hypothesis:
  #     theme: clean
  #     openSidebar: false
  downloads: ~
  sharing: ~
  sidebar:
    title: ~
    logo: ~
    search: true
    contents: ~
    style: floating
    background: ~
    foreground: ~
    border: true
    alignment: left
    collapse-level: 3
    pinned: true
    header: ""
    footer: ""
  margin-header: ~
  page-footer:
    left: ~
    right: ~
  chapters:
  - index.qmd
  - instructions.qmd
  appendices:
  - references.qmd
```
:::

#### html Options

The `format` key defines options for specific formats, such as html or pdf. We'll only be using html here ([quarto reference](https://quarto.org/docs/reference/formats/html.html#format-options)).

::: {.callout-note collapse="true"}
## format:html key

``` yaml
format:
  html:
    theme:
      light:
      - flatly
      - include/light.scss
      dark:
      - darkly
      - include/dark.scss
    css:
    - https://use.fontawesome.com/releases/v5.13.0/css/all.css
    - include/booktem.css
    - include/glossary.css
    - include/style.css
    df-print: kable
    code-link: true
    code-fold: false
    code-line-numbers: true
    code-overflow: wrap
    code-copy: hover
    highlight-style: a11y
    mainfont: ~
    monofont: ~
    include-after-body: [include/script.js]

```
:::

### Crossrefs {#sec-crossrefs}

Section links must start with `sec-` and look like this: @sec-snippets.

```{verbatim, lang = "md"}
## Section Title {#sec-section-title}

Internal links look like this: @sec-section-title
```

Figure links must start with `fig-` and look like this: @fig-poisson. 

```{r fig-poisson, echo = FALSE}
#| fig-cap: "A histogram of a Poisson distribution with lambda = 3"
hist(rpois(1000, lambda = 3))
```

Table links must start with `tbl-` and look like this: @tbl-authors. 

```{r tbl-authors, echo = FALSE}
#| tbl-cap: "The authors of this book"

data.frame(
  first_name = c("Lisa", "Daniël"),
  last_name = c("DeBruine", "Lakens")
)
```


See the [quarto documentation](https://quarto.org/docs/books/book-crossrefs.html){target="_blank"} for more information.

### References {#sec-refs}

Zotero export - keep updated


### Snippets {#sec-snippets}

Snippets in RStudio provide shortcuts to syntax. For example, in an RMarkdown document, type "r" and shift-tab to expand a code chunk.

You can add your own snippets. Under the **`Tools`** menu, choose **`Edit Code Snippets...`** and paste the following text into the end of the appropriate sections.

#### Markdown

```
snippet gls
	r glossary("${1:term}")
	
snippet gls2
	r glossary("${1:term}", "${2:display}")
	
snippet h1
	# ${1:title} {#sec-${2:ref}}
	
snippet h2
	## ${1:title} {#sec-${2:ref}}
	
snippet h3
	### ${1:title} {#sec-${2:ref}}
	
snippet h4
	#### ${1:title} {#sec-${2:ref}}
	
snippet h5
	##### ${1:title} {#sec-${2:ref}}
```

### Customize

#### Page Footer

The default footer includes license YEAR, author, and github and twitter icons, but you can customize this in the _quarto.yml file under `page-footer:`. See  the [quarto documentation](https://quarto.org/docs/reference/projects/websites.html#footer) for more options. See the available icons at <https://icons.getbootstrap.com/>.


## Layout {#sec-layout}

### Conventions {#sec-conventions}

This book will use the following conventions:

* Code: `list(number = 1, letter = "A")`
* File paths: <path>data/sales.csv</path>
* Menu/interface options: <if>Tools > Global Options... > Pane Layout</if>
* R Packages: <pkg>tidyverse</pkg>
* Glossary items: `r glossary("alpha")`
* Citations: @usethis
* Internal links: @sec-conventions
* External links: [Mastering Shiny](https://mastering-shiny.org/){target="_blank"}
* Mac-specific: <mac>Cmd-Shift-F10</mac> 
* Windows-specific: <pc>Ctl-Shift-F10</pc>

A list of mac and windows [keyboard shortcuts](https://support.posit.co/hc/en-us/articles/200711853-Keyboard-Shortcuts-in-the-RStudio-IDE).


### Figures {#sec-figures}

It is best practice to set a custom ggplot theme, then each subsequent plot will use that theme. You can put this code in <path>R/my_setup.R</path> after loading <pkg>ggplot2</pkg>.

Start with a built-in theme and then add any tweaks with the `theme()` function.

```{r}
library(ggplot2)

my_theme <- theme_minimal(base_size = 16) + 
            theme(panel.background = element_rect(fill = "red", 
                                                  color = "black", 
                                                  size = 5),
                  panel.grid = element_blank())
theme_set(my_theme)
```


```{r fig-diamonds}
#| fig-cap: "Demographic information of midwest counties from 2000 US census"
#| fig-asp: 1
ggplot(midwest, aes(popdensity, percollege)) +
  geom_point(alpha = 0.5) +
  labs(x = "Population Density", y = "Percent College Educated")
```

### Tables {#sec-tables}


```{r tbl}
#| tbl-cap: "Beavers"
head(beaver1)
```


### Callout boxes {#sec-callout}

See the [quarto reference](https://quarto.org/docs/authoring/callouts.html) for more options.]{.aside}

::: {.callout-note}
.callout-note: Informational asides.
:::

::: {.callout-note collapse="true"}
## Click to expand
colapse = "true": Expanded!
:::

::: {.callout-tip}
.callout-tip: Tips
:::

::: {.callout-warning}
.callout-warning: Notes to warn you about something.
:::

::: {.callout-caution}
.callout-caution: Notes about things that could cause serious errors.
:::

::: {.callout-important}
.callout-important: Notes about things that are important.
:::


### Code and Output {#sec-code-output}

```{r}
# code chunks
paste("Code", "Output", 1, sep = " ")
```

```{r, filename = "Filename or header"}
# code chunks with filename
a <- 1
```

```{r, eval = FALSE, verbatim="r, fig.width = 2, fig.height = 2"}
# code chunks with visible headers
hist(rnorm(100000))
```

```{verbatim, lang = "md"}
## Markdown Example

* Inline code: `r nrow(iris)`
* *Italics*
* **Bold**
* [Linked text](https://psyteachr.github.io)
```



### Fonts {#sec-fonts}




## Extras {#sec-extras}

### Glossary {#sec-glossary}

Books are set up with lightweight glossary functions from the [glossary](https://debruine.github.io/glossary/) package. 

```{r}
# code in R/my_setup.R to initialise the glossary on each page
library(glossary)
glossary_path("include/glossary.yml")
glossary_popup("click") # "click", "hover" or "none"
```

Edit the file `glossary.yml` with your glossary terms like this:

``` yaml
alpha: |
  The threshold chosen in Neyman-Pearson hypothesis testing to distinguish test results that lead to the decision to reject the null hypothesis, or not, based on the desired upper bound of the Type 1 error rate. An alpha level of 5% it most commonly used, but other alpha levels can be used as long as they are determined and preregistered by the researcher before the data is analyzed.
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.
```

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 definition with `glossary("p-value", show = "def")`: `r glossary("p-value", show = "def")`

Show the table of terms defined on this page with `glossary_table()`:

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

### FontAwesome

The [fontAwesome quarto extension](https://github.com/quarto-ext/fontawesome) allows you to use the [free icons](https://fontawesome.com/search?m=free) with syntax like:

```
{{< fa dragon >}}
{{< fa brands github size = 5x title="(github logo)" >}}
```

To install it, just run this code in the Terminal pane of RStudio (not the Console pane).

``` bash
quarto install extension quarto-ext/fontawesome
```