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))

Meadors

See my answer to a related question for an experimental approach to the problem. – Kall

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).

Meadors

You have to press the Like button if you want to give kudos. – Winterwinterbottom

He replied not done in roxygen3 in 2013. It's 2019 and here we are still in roxygen2, nothing's changed to this problem. Manually updating .Rd files is horrible. – Principally

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:

Sophey