Using the `glossaries` LaTeX package

The glossaries package

The glossaries LaTeX package can be used to manage key expressions (usually technical terms and acronyms). It allows you to quickly generate a glossaries page with definitions, related terms, and page numbers to where the terms appear in the text. Hyperlinks between instances in the text and its glossary entry can easily be generated.

Bookdown support for this package is currently lacking for generic outputs, see Issue #199. However, there are no issues for PDF output using LaTeX.

LaTeX usage

The LaTeX workflow is straight-forward:

• import the package in the header: \usepackage{glossaries}
• create glossary entries using the \newglossaryentry command
• generate glossary indexing using the \makeglossaries (it uses Makeindex)
• use key terms in the text using the \gls{} (referring to the aformentioned entries)
• add the glossary content to the document \printglossary

Because of its use of Makeindex, you may need to create two LaTeX passes. Some tools detect this and create two passes automatically. This is the case when knitting a bookdown document using RStudio.

bookdown usage

Below we will review how these steps can be incorporated into a bookdown project.

LaTeX header / preamble

There are two ways to add LaTeX to the header/preamble from the bookdown yaml block.

1. source file contents using the in_header block
2. source inline contents using header-includes block

Both methods are valid and can work together. The official bookdown documentation suggests to use in_header for the preamble and we provide examples that use header-includes to import packages.

Care must be taken here because of the import order between the two methods: in_header is imported first followed header-includes. It will not work to provide the \makeglossaries command via in_header and to import the package by adding \usepackage{glossaries} to the header-includes block.

It may be best (and clean) to contain all of the glossary header/preamble content in a single tex file, for example, glossary.tex

\usepackage[nonumberlist]{glossaries}

\makenoidxglossaries

\newglossaryentry{Set} {
  name=Set,
  description={A Set contains fishing or oceanograpic activity made at a particular \gls{Station}. Results recorded at a particular Station are saved to the Set. The Set contains metadata such as time and recorded GPS coordinates for all activity it contains. Multiple Sets can be made for the same station.
  }

\newglossaryentry{Station} {
  name=Station,
  description={A target coordinate where a \gls{Set} is to be performed. 
  }

\glsaddallunused

and to include the contents of the glossary.tex file just via the in_headermechanism:

output:
 csasdown::techreport_pdf:
   includes:
     in_header: "glossary.tex"
   french: false
   # copy_sty is a toggle to copy the style file from the csasdown package every time you compile
   # the document. If false, any changes you have made to the style file in your project
   # will remain between compilations. If true, your changes will be lost when you compile
   copy_sty: true

LaTeX document

Content can be added in the document. You can simply make it known that a word from the glossary is used using the gls{} in your markdown text:

# Introduction {#sec:introduction}
Sometimes more than one \gls{Set} is taken at the same \gls{Station}.
This is the case for when both trawling and CTD data need to be recorded for the same station.

LaTeX block

`r if(knitr:::is_latex_output()) '% begin csasdown appendix'`
`r if(!knitr:::is_latex_output()) '# (APPENDIX) Appendix {-}'`

<!-- No need to create a section header, it is done by \printnoidxglossary -->
<!-- see glossary.tex for glossary entries -->
```{=latex}
\printnoidxglossary[sort=word]
```
`r if(knitr:::is_latex_output()) '% end csasdown appendix'`