Advanced usage

Using other Pandoc arguments

The default syntax, pandoc_args: !expr acronymsdown::add_filter() is effective for getting quickly set up, but does not allow registering other Pandoc arguments.

When other arguments are necessary, for example wrap=preserve, an alternative syntax can be used to specify all arguments as a list:

---
output:
  pdf_document:
    pandoc_args:
     - !expr acronymsdown::add_filter()
     - --wrap=preserve
     - Other arguments here...
---

As in vignette("acronymsdown"), please note that pdf_document is only used as an example. Other output formats can be used, and if multiple output formats are declared in the metadata, the pandoc_args list should be duplicated. The arguments themselves may be different for each format, with the exception of !expr acronymsdown::add_filter() that should be used in all formats.

For example:

---
output:
  pdf_document:
    - !expr acronymsdown::add_filter()
    - --wrap=preserve
  html_document:
    - !expr acronymsdown::add_filter()
    - --shift-heading-level-by=1
---

Defining acronyms in external file(s)

Whereas defining acronyms directly in the YAML metadata is the most straightforward way, acronymsdown also support reading definitions from one (or several) pseudo-YAML file.

To do so, simply specify the file path in the fromfile attribute of the YAML metadata. This behaviour is particularly useful if you want to define acronyms in the same file for multiple projects, or generate it automatically, in a similar way to the .bib files for LaTeX citations.

This attribute may be either a single path, for example:

---
acronyms:
  fromfile: ./acronyms.yml
---

or a list of paths, for example:

---
acronyms:
  fromfile:
    - ./acronyms1.yml
    - ./acronyms2.yml
---

Note that the path may be either absolute or relative. If the path is relative, it is resolved with respect to the current working directory of Pandoc. By default, when using rmarkdown, this working directory is set to the directory containing the source Rmd file.

In our examples, we thus assume that the acronyms.yml (respectively, acronyms1.yml and acronyms2.yml) live in the same folder as the Rmd document.

The content of such files must be as following:

---
acronyms:
  keys:
    # Define your keys here
    - shortname: Rmd
      longname: RMarkdown document
---

Please note that this format is not really YAML ; instead, the files are read as Markdown documents themselves, hence the presence of the --- fences.

However, only the metadata and more specifically the acronyms.keys field is used. No other option is taken into account. The eventual document body is ignored as well.

The acronyms are read in the following order:

1. Acronyms in the acronyms.key field of the source Rmd document, in sequential order.
2. Acronyms in each of the acronyms.fromfile files.
   1. Files are read in sequential order.
   2. Acronyms inside each file are also read in sequential order.

This order is meaningful in 2 cases:

• When a duplicate key is found, the behaviour (keep or replace) depends on the order in which acronyms are read.
• When the initial sorting is used, the List Of Acronyms displays acronyms in the same order as they were defined.

Integrating acronymsdown in custom formats

The simplest way to use acronymsdown is to add it to the list of Pandoc arguments, using the pandoc_args: !expr acronymsdown::add_filter syntax.

However, if you find this quite repetitive across multiple documents, or if you are developing a custom output format, you may want to add acronymsdown directly to the format’s default options.

As per the rmarkdown documentation (vignette("lua-filters", "rmarkdown")), this can be achieved by using a code similar to the following example:

custom_format <- function(...) {
  base_format <- rmarkdown::html_document(...)
  # prepending a new Lua filter to html_document() ones
  base_format$pandoc$lua_filters <- c(
    acronymsdown::path_to_filter(),
    base_format$pandoc$lua_filters
  )
  base_format
}

In this example, the rmarkdown::html_document format was used as a base format. However, any output format may be used, as long as they were created “correctly”, i.e., as long as rmarkdown::is_output_format returns TRUE for this format.

A completely new format can be created in a similar fashion, instead of using a base format. The important point is to add acronymsdown::path_to_filter() to the list of Lua Filters, which can be done using the rmarkdown::pandoc_options function when creating a new format.

Please refer to the rmarkdown documentation for more details, in particular vignette("lua-filters", "rmarkdown"), ?rmarkdown::output_format, and ?rmarkdown::pandoc_options.

Using acronymsdown with Quarto

A specific Quarto extension has been developed for Quarto users. It contains all the features of Acronymsdown, with an even easier usage!

Simply type the following command in your terminal to install the acronyms Quarto extension:

quarto add rchaput/acronyms

Then, load the filter in your document metadata with:

---
filters:
  - acronyms
---

and start using acronyms in your document!

Please refer to the documentation for detailed instructions.

Using acronymsdown with only Pandoc / without RMarkdown

acronymsdown is implemented using a Pandoc Lua Filter, whereas the R package is provided as a “simple” wrapper to facilitate using this filter.

This means that R (and by extension RMarkdown) are not necessary to use acronymsdown, although they make it easier.

To run acronymsdown through Pandoc only, please follow these steps:

1. Make sure that Pandoc is available on your system, either by using your distribution’s package manager, or by downloading manually one of their releases. Note: the bare minimum requirement is version 2.0, however acronymsdown might not work on old versions. To avoid bugs, please use a recent version.

2. Make sure that acronymsdown’s Lua files (from the inst/ folder) are available and readable. To do so, 2 options are available:

   1. If the R package is installed on your system, the Lua files are already included. To get the path to the filter (/path/to/parse-acronyms.lua), you may use the R method acronymsdown::path_to_filter(). Please note this path, you will need it in the next step.

   2. You may also download the acronymsdown-pandoc.zip archive from one of our releases, which contains these files, and unzip it to a convenient location. Please remember this location, you will need it in the next step.

3. Execute Pandoc and pass the additional arguments to it:

pandoc --lua-filter /path/to/parse-acronyms.lua input.md

where /path/to/parse-acronyms.lua is the path to the parse-acronyms.lua file, according to your installation method, and input.md is the document you want to parse.

Note: all the Lua files from the inst/ folder must be available on your system, in the same folder! The “main” script, parse-acronyms.lua, which must be loaded by Pandoc, relies on them and will not work if they are not in the same folder.