Can R help manuals have latex math in them?

Question

I am working on an R package and I am using the package Roxygen2 to write the help manuals for my R functions. What I would like to know is if it is possible to use latex for math equations in the manual pages?

For example, if I had a function called add2 that did the following:

add2 = function(x,y){
       z = x+y
       return(z)
}

And using Roxygen2 documentation I had the following:

##' @include add2.R
{}

##' Compute the sum of x_1 and x_2
##'
##' Computes the sum of x_1 and x_2
##'
##' @param x_1 number of guys
##' @param x_2 number of girls
##' @return The sum of the two values x_1 and x_2
##'
##' @example examples/adding.R
##' @export
##' @author Name

And this works for me, but this displays x1 and x2 as x_1 and x_2 in the help manual whereas I would like for it to look like latex math and actually have the subscripts on x, i.e., $x_1$ and $x_2$ in latex.

Is there any way to do this or does R not accomodate this?

Answer 1

Sort of. Use something like \eqn{x_1} if you want use the (unprocessed) version of the LaTeX markup in plain-text output (alternately you could say something like \eqn{x_1}{x1}). The "sort of" part is that I'm not sure offhand for which particular output formats the LaTeX processing will be done -- for example, I'm guessing that the HTML-formatted version of output you would see in (e.g.) an RStudio documentation pane would not respect this markup. (The LaTeX markup definitely will be used in the PDF versions of the manual, which I almost never look at ...)

I'm going to go ahead and quote from the Mathematics section of Writing R Extensions ...

Mathematical formulae should be set beautifully for printed documentation yet we still want something useful for text and HTML online help. To this end, the two commands \eqn{latex}{ascii} and \deqn{latex}{ascii} are used. Whereas \eqn is used for “inline” formulae (corresponding to TeX’s $…$), \deqn gives “displayed equations” (as in LaTeX’s displaymath environment, or TeX’s $$…$$). Both arguments are treated as ‘verbatim’ text.

Both commands can also be used as \eqn{latexascii} (only one argument) which then is used for both latex and ascii. No whitespace is allowed between command and the first argument, nor between the first and second arguments.

The following example is from Poisson.Rd:

\deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{%

p(x) = \lambda^x exp(-\lambda)/x!} for \eqn{x = 0, 1, 2, \ldots}.

---

As of 2020-05-08, the mathjaxr package, by Wolfgang Viechtbauer, is on CRAN. It

Provides 'MathJax' and macros to enable its use within Rd files for rendering equations in the HTML help files.

From the README file:

[After installing the package, editing the package DESCRIPTION file appropriately, and adding \loadmathjax{} to the Rd file ... a]n inline equation can then be added with the \mjeqn{latex}{ascii} macro, with the LaTeX commands for the equation given between the first set of curly brackets (which will be rendered in the HTML and PDF help pages) and the plain-text version of the equation given between the second set of curly brackets (which will be shown in the plain text help). With the \mjdeqn{latex}{ascii} macro, one can add ‘displayed equations’ (as in LaTeX’s displaymath environment).