Documenting equations with deqn and roxygen

Question

I'm using \deqn{}{} with roxygen2 to document equations for a function in a package. The LaTeX (the 1st argument to deqn) renders fine because white space is ignored in LaTeX equations, but I have a problem with the ASCII (the 2nd argument to deqn) representation.

The problem is that my formatting is destroyed (it appears roxygen puts the entire deqn command on a "single line" and then wraps that line at ~60 columns or so). Is there a way to force roxygen2 to preserve the white space formatting in my roxygen commands/comments in the .R file?

I have the following code in a file, example.R:

#'Example
#'
#'deqn ASCII example
#'
#'\deqn{ \sigma = \sqrt{ \frac{Z}{n} \sum
#'  \left[ \textstyle\frac{1}{2}\displaystyle
#'    \left( \log \frac{H_i}{L_i} \right)^2  - (2\log 2-1)
#'    \left( \log \frac{C_i}{O_i} \right)^2 \right] }
#'}{sqrt(N/n * runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 -
#'           (2*log(2)-1) * log(OHLC[,4]/OHLC[,1])^2, n))}
#'
#'@param x An example parameter
#'@return A example result
#'@author Joshua Ulrich
#'@keywords ts
#'@export
"example" <-
function(x) {
}

And I use the following R code to generate the example.Rd file:

library(roxygen2)
setwd("dir/containing/example.R/")
dir.create("man",FALSE)
roclet <- rd_roclet()
roc_proc(roclet, "example.R", ".")
roc_out(roclet, "example.R", ".")

You can generate the text representation of the example.Rd file using this command at the command line:

R CMD Rd2txt dir/containing/example.R/man/example.Rd

The Details section of the output from the above command looks like:

sqrt(N/n *
  runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 - (2*log(2)-1) *
  log(OHLC[,4]/OHLC[,1])^2, n))

whereas I would like it to look like:

sqrt(N/n * runSum(0.5 * log(OHLC[,2]/OHLC[,3])^2 -
         (2*log(2)-1) * log(OHLC[,4]/OHLC[,1])^2, n))

Answer 1

According to Hadley Wickham, line wrapping will be removed in future versions of roxygen. So the solution for roxygen2 is to roxygenize the file (or package), then manually update the text equation in the affected .Rd file(s).

Answer 2

This answer doesn't address your ASCII issue, but it currently is my go-to way when rendering latex equations in HTML, so I hope this helps you.

Take a look at the mathjaxr package (CRAN, GitHub). You can install it either with install.packages("mathjaxr") or remotes::install_github("wviechtb/mathjaxr").

It introduces a macro \loadmathjax that loads the necessary JavaScript from MathJax to render latex equations. Then use the macro \mjeqn{latex}{ascii} or \mjdeqn{latex}{ascii} instead of \eqn or \deqn and you're good to go.

In your specific example, we'd have the following:

#' Example
#'
#' Example mathjax function
#'
#' \loadmathjax
#' \mjdeqn{ \sigma = \sqrt{ \frac{Z}{n} \sum
#'   \textstyle\frac{1}{2}\displaystyle
#'     \left\[ \left( \log \frac{H_i}{L_i} \right)^2  - (2\log 2-1) \left( \log \frac{C_i}{O_i} \right)^2 \right] }
#' }{ASCII representation}
example <- function(a, b, c) {}

(notice the open square bracket is escaped)

If you use RStudio, you may run into some trouble with the \loadmathjax macro. To preview the content quickly, do the following:

1. Generate documentation (Ctrl + Shift + D or devtools::document(roclets = c('rd', 'collate', 'namespace')))
2. Call preview_rd("example.Rd") to preview the documentation

When you're done, you can inspect the final result with these steps:

1. Generate documentation (Ctrl + Shift + D or devtools::document(roclets = c('rd', 'collate', 'namespace'))
2. Install the package (Ctrl + Shift + L or devtools::install())
3. Restart the R session with .rs.restartR()
4. Preview documentation with ?example

Either way should produce the following result: