---
title: "Lua filter to replace ampersands in in-text citations"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Lua filter to replace ampersands in in-text citations}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library("rmdfiltr")
```


# Using the ampersand replacement filter

The aim of the filter is to replace ampersands in in-sentence citations generated by `citeproc` (or `pandoc-citeproc`).
`citeproc` relies on the [Citation Style Language](https://en.wikipedia.org/wiki/Citation_Style_Language) (CSL) to specify citation styles.
A drawback of this standard is, that it does not specify citations that are part of the sentence, rather than in parentheses.
Hence, `citeproc` uses the same style for both citation forms.
Some author-year citation styles, however, demand slightly different styles for in-sentence and in-parentheses citations.
For example, according to APA style author names should be joined by `&` in parentheses but by `and` in a sentence.
The ampersand replacement filter addresses this problem, by replacing ampersands in in-sentence citations with `and` or its equivalent in other languages.
This, of course, necessitates that the filter is applied *after* `citeproc`.
To do so, it is necessary to disable the default application of `citeproc`, because it is always applied last, by adding the following to the documents YAML front matter:

~~~yaml
citeproc: no
~~~

To manually apply `citeproc` and subsequently the ampersand replacement filter add the `pandoc` arguments to the output format of your R Markdown document as `pandoc_args`.
Each filter returns a vector of command line arguments; they take previous arguments as `args` and add to them.
Hence, the calls to add filters can be nested:

```{r single-filter-display, eval = FALSE}
library("rmdfiltr")
add_citeproc_filter(args = NULL)
```

```{r single-filter, echo = FALSE}
library("rmdfiltr")
add_citeproc_filter(args = NULL, error = FALSE)
```

```{r nested-filters-display, eval = FALSE}
add_replace_ampersands_filter(add_citeproc_filter(args = NULL))
```

```{r nested-filters, echo = FALSE}
add_replace_ampersands_filter(add_citeproc_filter(args = NULL, error = FALSE), error = FALSE)
```

When adding the filters to `pandoc_args` the R code needs to be preceded by `!expr` to declare it as to-be-interpreted expression.

~~~yaml
output:
  html_document:
    pandoc_args: !expr rmdfiltr::add_replace_ampersands_filter(rmdfiltr::add_citeproc_filter(args = NULL))
~~~

By default, it is assumed that the document language is English and `&` is replaced by `and`.
Other languages can be specified with the `pandoc` variable [`lang`](https://pandoc.org/MANUAL.html#language-variables), which requires a language and region tag.
For example, to replace `&` by the German `und` add the following to the document YAML front matter:

~~~yaml
lang: de-DE
~~~

Currently, [Dutch, English, German, and Spanish are supported](https://github.com/crsh/rmdfiltr/blob/03b9715b7ccc69e5eeaf9ef39fd77484e4fb8fdd/inst/replace_ampersands.lua#L3).