Search code examples
rr-markdowncross-reference

RStudio rticles knit to pdf book fails when cross-referencing equations

Ramping up for a new conference article, I want to use rticles and make use of the cross-referencing features of bookdown. This originally failed when using the standard equation and cross-referencing example (e.g. compare for https://bookdown.org/yihui/bookdown/cross-references.html).

The original error message read: 

! Undefined control sequence.
l.430 See equation \eqref
                         {eq:linear} for more insights.

Eliminating the cross-reference pointer \@ref(eq:linear) made knit complete. However, I - obviously - lost the cross-reference to the equation.

following an update of all R packages, the Rmd is knitted without throwing an error. However, the cross-reference is not automatically inserted, instead the \@ref(eq:linear) is printed.

I assume the issue is related how such references (aka control sequences) are processed during the knitting. :( I have no idea how to handle this.

This SO-question Cross-referencing in rticles provides pointers to the official documentation from which the example is taken over.

Thanks for shedding some light on me how to format the equation reference.

---
title: "rticles fails knitting equation references"
keywords: ["keyword 1", "keyword 2"]
abstract: |
  The abstract goes here.
  On multiple lines eventually.
## hook up rticles as base format with bookdown for referencing, etc
output:
  bookdown::pdf_book:
    base_format: rticles::ieee_article
---

Introduction
=============

To add math, I do the following

See equation \@ref(eq:linear) for more insights.

\begin{equation}
a + bx = c  (\#eq:linear)
\end{equation}

More cool text.
Solution

  • Referencing equation with \eqref requires the amsmath Tex package.

    For this specific format ieee_article, the use of amsmath is conditional to a pandoc variable. You need to add this in your yaml header

    with_amsmath: true

    You can add any Tex packages for any rmarkdown format using the extra_dependencies argument in the format output.

    Here it could also works like this

    output:
  bookdown::pdf_book:
    base_format: rticles::ieee_article
    extra_dependencies: amsmath

    (but it is not recommended to comply with IEEE requirements here, as the template includes a configuration for amsmath)