Manage a glossary with bookdown

  • pandoc
  • bookdown
  • thesis

How to easily link glossary terms/acronyms from the text body to a glossary page

Author
Published

When writing a (long) manuscript, it is often useful to add a glossary. With LaTeX the glossary is properly managed with the acronym package. But, neither Pandoc nor bookdown provide a proper way to do this (see this issue).
With bookdown, the common basic proposed solution is to put the acronyms in a data file (e.g. in csv format or xslx) and then render a the glossary page (see e.g. [1], [2]). However, these simple solutions do not link from the acronym in the text body to the glossary page, as is the case with the LaTeX acronym package.

My solution effectively use the above basic solution with the adds of an anchor on each acronyms and terms:

Example

For instance, if you have the following csv data file in acro.csv:

abbrv descr
2D two-dimension
3D three-dimension

the following markdown will be generated using print_acro(acro.csv)

[2D]{#acro-2D .acronym-item}
:   two-dimension

[3D]{#acro-3D .acronym-item}
:   three-dimension

One can link to the glossary page as follows:

In [2D](#acro-2D){.acroterm} you get [...]

Bookdown is then able to generate a link the anchor in the glossary page (i.e. where you have called print_acro(acro.csv)).
Next, if you’re using Rstudio (or any IDE that does the same), you can add a snippet, such as:

snippet acro
    [${1:acro}](#acro-${1:acro}){.acroterm}

With this, one can easily add an acronym in the text body, and that, for any pandoc output format!

Tip

You can change the snippet to include the abbr HTML tag, but this work only with HTML like output ☹️

Nevertheless, it remains that the management of plural forms is not yet possible (although LaTeX acronym package allows it)… In my opinion, the only way that may allow such functionality is to define some specific (R) function (or a specific package?).

Edit: I found recently this package https://github.com/yonicd/glossaries (but not curently tested)

References

[1]
Yongfu’s Blog, “Create a Glossary in R Markdown.” [Online]. https://yongfu.name/2018/10/24/glossary-maker/. [Accessed: 23-March-2023]
[2]
Yongfu’s Blog, “Setting up a Glossary.” [Online]. Available: https://ewfrees.github.io/StyleGuideLDA/setting-up-a-glossary.html. [Accessed: 23-March-2023]