# Lua filter to replace ampersands in in-text citations

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

    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:

    library("rmdfiltr")
    add_citeproc_filter(args = NULL)

    #> [1] "--citeproc"

    add_replace_ampersands_filter(add_citeproc_filter(args = NULL))

    #> [1] "--citeproc"
    #> [2] "--lua-filter"
    #> [3] "/private/var/folders/nv/mz4ffsbn045101ngdd_mx0th0000gn/T/RtmpUaG0vc/Rinst1019a4a86f794/rmdfiltr/replace_ampersands.lua"

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

    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`, which requires a language and region tag. For example, to replace `&` by the German `und` add the following to the document YAML front matter:

    lang: de-DE

Currently, Dutch, English, German, and Spanish are supported.