4  Cross References

When authoring the book, it is common to need to cross reference book parts (i.e., chapters, sections), figures, tables, and I’m going to go ahead and include citations here too.

4.1 Book parts

Link to the official documentation. Briefly, there are two methods that I’m likely to use.

4.1.1 Reference a chapter

First, you need to make a chapter/section heading available to be referenced by adding {#sec-} behind the header. For example:

# Images {#sec-images}

Then to reference it you type @sec-. For example:

See @sec-images to learn about images.

Which looks like this: See Chapter 7 to learn about images.

Label Prefix

For a chapter to be cross-referenceable, its label must start with the sec- prefix.

Chapter in _quarto.yml

For a chapter to be cross-referenceable, it must be listed in _quarto.yml.

If I don’t want @sec-images to automatically be replaced with Chapter 7 – for example, I want it to say the images chapter instead – then I think I will need to use hyperlinks ( below). For example,

See [the images chapter](../images/images.qmd)

Which looks like this: See the images chapter

Hyperlink file paths

When using hyperlinks to connect chatpers/sections, make sure to use the full file path (originating from the current qmd file). For example, use ../images/images.qmd instead of just images.qmd. If you change the file structure, you may break the links. This is one reason why you may want to use that @sec- syntax whenever possible.

Chapter sections work the same way. You are able to cross-reference any heading at any level. For example,

4.2 Citations

To add a citation to the text of a chapter:

  1. Add an entry to references.bib in BibTeX format.
    • The easiest way to get the BibTeX citation is probably to generate it with a reference management software like PaperPile or Zotero.
  2. Use the @referenceTitle syntax to add the citation to your text.

For example:

Built-in example: See @knuth84 for additional discussion of literate programming.

Renders as: Built-in example: See1 for additional discussion of literate programming.

4.2.1 Change the citation style

To change the citation style

  1. Add a CSL file to the repo. For example, this repo has a file named ama.csl. The Quarto Citations and Footnotes documentation also includes links to download CSL files for a variety of citation formats.

  2. Update the csl: option in _quarto.yml. For example, csl: ama.csl.

Here is what the default @knuth84 citation above looks like after rendering this document.

Figure 4.1: An example of Quarto’s default citation style.

Here is what the default @knuth84 reference looks like after rendering this document.

An example of Quarto’s default reference style.

Here is what the @knuth84 citation above looks like after changing the citation style to AMA and rendering this document.

Figure 4.2: An example of an AMA citation.

Here is what the @knuth84 reference looks like after changing the citation style to AMA and rendering this document.

Figure 4.3: An example of an AMA reference.

4.3 Footnotes

I haven’t done a lot of footnotes in the past, but here is some documentation in case I want to do them in the future.1

4.4 Glossary

Following the emphasizing text guidance in the R4Epi Wiki, we sometimes want to hyperlink words that we will define in the Glossary. We can definitely link selected words in the narrative of the chapters to headings, but that approach creates a line in the table of contents for each word in the glossary, which isn’t ideal. I posted this issue on Stack Overflow. Therefore, the best strategy so far seems to be using definition lists.

For example, let’s say that we want to define the term data frame in the glossary. The first thing we do is assign and CSS ID to the word “data frame” in the glossary qmd file. For now, I’m planning to prefix all glossary IDs with the word “glossary” in case I need to search for them later.

[Data frame]{#glossary-data-frame} 

:  For our purposes, data frames are just R's term for data set or data table. Data frames are made up of columns (variables) and rows (observations). In R, all columns of a data frame must have the same length.
Definition lists

The colon followed by two spaces before the term’s definition is not optional.

Next, use a hyperlink to reference the glossary term in the narrative of the chapter. For example,

We want to define the term [data frame](../appendices/glossary.qmd#glossary-data-frame) in the glossary.

Which looks like this: We want to define the term data frame in the glossary.

Additionally, terms linked in this way should also work in PDF downloads.

If we want to adjust the style of the of the glossary term (e.g., increase the font size or make it bold), we can do so in the .scss file. For example,

dl {
  font-size: 14pt;
  font-weight: bold;
}

We use dl because Pandoc renders the HTML output to description list (<dl>) elements. This styling should also work in PDF downloads.

  1. And here is an example footnote.↩︎