Using the ampersand replacement filter

The aim of the filter is to replace ampersands in in-sentence citations generated by pandoc-citeproc. pandoc-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, pandoc-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 pandoc-citeproc. To do so, it is necessary to disable the default application of pandoc-citeproc, because it is always applied last, by adding the following to the documents YAML front matter:

citeproc: no

To manually apply pandoc-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] "--filter"                                                       
#> [2] "/Applications/RStudio.app/Contents/MacOS/pandoc/pandoc-citeproc"

add_replace_ampersands_filter(add_citeproc_filter(args = NULL))

#> [1] "--filter"                                                                                                            
#> [2] "/Applications/RStudio.app/Contents/MacOS/pandoc/pandoc-citeproc"                                                     
#> [3] "--lua-filter"                                                                                                        
#> [4] "/private/var/folders/nv/mz4ffsbn045101ngdd_mx0th0000gn/T/Rtmpp9G8mG/Rinsta4a16c970fe/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.