[R] Displaying Equations in Documentation

Prof Brian Ripley ripley at stats.ox.ac.uk
Tue Aug 26 09:29:12 CEST 2008


On Tue, 26 Aug 2008, Rolf Turner wrote:

>
> On 26/08/2008, at 4:50 AM, Jarrett Byrnes wrote:
>
>> I'm currently working on writing up some documentation for some of my code, 
>> but am having the darndest time coding in equations.  For example, the 
>> equation in the following:
>> 
>> \details{ Calculated the R Squared for observed endogenous variables in a 
>> structural equation model, as well as several other useful summary 
>> statistics about the error in thoe variables.
>> 
>> R Squared values are calculated as
>> 
>> \deqn{R^{2} = 1-\frac{estimated variance}{observed variance}}
>> 
>> Standardized error coefficients are then calculated as sqrt(1 - R^2).
>> }
>> 
>> While it shows normally using R CMD Rd2dvi, when I actually compile and 
>> load the package, displays as follows:
>> R^{2} = 1-frac{estimated variance}{observed variance}
>
> 
>
> 	Displays, presumably, in a plain text or html environment.
>
> 	As my late Uncle Stanley would have said, ``What the hell do you 
> expect?''
>
> 	Plain text and html, unlike LaTeX, do not have advanced mathematical 
> display
> 	capabilities.

That's not the whole story for HTML, as there is MathML.  At the time the 
decisions were made for Rd rendering, MathML was pretty much unsupported. 
That has changed slowly, and nowadays some browsers (e.g. Firefox, Opera) 
do support Presentation MathML -- unfortunately they often are short of 
suitable fonts.  AFAIK, Safari and IE (including Compiled HTML) do not yet 
support it.

So someone interested could rewrite the Rdconv code to make use of MathML, 
but for now the subset of R users who could benefit from it would be 
small.

> 	The R documentation facility --- RTFM!!! (section 2.6 Mathematics) 
> --- provides a way
> 	to allow for both possibilities.  You can do:
>
> 	\deqn{R^2 = 1 - \frac{estimated variance}{observed 
> variance}}{R-squared = 1 - (estimated variance)/(observed variance)}
>
> 	Then in the pdf manual for your package you'll get the sexy 
> mathematical display, but when you call
> 	for help on line and get a plain text or html version you'll see
>
> 		R-squared = 1 - (estimated variance)/(observed variance)
>
> 	which is the best that can be done under the circumstances 
>> 
>> I have also tried
>> 
>> \deqn{R^{2} = 1-\frac{{estimated variance}{observed variance}}}
>> 
>> and
>> 
>> \deqn{R^{2} = \frac{1-{estimated variance}{observed variance}}}
>> 
>> with the same result - Rd2dvi is happy, but the display is still wonky in 
>> practice.  I've also tried subbing in \eqn{R^{2}} in the rest of the text 
>> in a few places, but, again, it shows as R^{2}.  Is there something I'm 
>> missing about inserting equations into R documentation?
>
> 	Yes.
>
> 		cheers,
>
> 			Rolf Turner
>
> ######################################################################
> Attention:\ This e-mail message is privileged and confid...{{dropped:9}}
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595



More information about the R-help mailing list