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/Rtmp7tDXDt/Rinst21297336bb2/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.