Search code examples
rlatexroxygen2

Can R help manuals have latex math in them?

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?

Solution

  • 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}.

    From this answer, LaTeX expressions specified as above will now be rendered in both HTML and PDF formats:

    Support for KaTeX in HTML rendering of Rd files was added in R 4.2.0. Support for amsmath in PDF rendering of Rd files was added in R 4.2.2. Hence packages with Depends: R (>= 4.3) can safely specify multiline equations using \deqn.