Math is not properly typeset in granovagg.1w documentation

[briandk]

Background

Building an R package produces two kinds of documentation:

1. A pdf manual which will be available on the package's CRAN page
2. in-line HTML help, available at the R console/app

Package PDF manuals can use LaTeX to typeset and display math, but the HTML help can't. So, R-documentation provides a workaround:

The Problem

The way .Rd files get parsed, the ASCII code in the fallback braces has to be escaped by a % sign (the comment symbol in LaTeX):

\eqn{LaTeX code goes here}{UNESCAPED ASCII CODE HERE WILL MAKE THE Rd PARSER THROW A FIT}
\eqn{LaTeX code goes here}{% Proper ASCII fallback code goes here, after a leading percent sign}

Unfortunately, the mechanism for handling escaping a percent sign in roxygen is currently broken and hasn't been fixed yet.

My current solution

I could hand-code ASCII fallback in the Rd files, but that would get obliterated every time we re-run roxygen on the package. So, I don't like that option.

For the time being, I'd like to write just straight ASCII instead of LaTeX. That means a (current) excerpt of the granovagg.1w help file looks exactly like this:

The L.C. can be written as a sum of products of the form MS.B = (1/df.B)(n_j (M_j - M..) M_j). The denominator of the F-statistic, MS.W (mean square within), can be described as a 'scaling factor'. It is just the (weighted) average of the variances of the J groups (j = 1 ... J). (n_j's are group sizes.) The differences (M_j - M..) are themselves the 'effects' in the analysis.

The PDF manual output of that ASCII looks like this:

If (and when) roxygen gets updated, we should be able to add the LaTeX code in gracefully. When we add LaTeX code, the appearance of the HTML in-line help files shouldn't change at all, but the PDF manual will be much prettier.