[Rd] Misuse of $<matn expressions>$ in Rd files

[Prof Brian Ripley]

'Writing R Extensions' tells you that $ needs to be escaped in Rd files 
outside \code and similar.  So I was surprised to find that ca 80 CRAN 
packages have constructions like (from ISwR)

   \item{\code{folate}}{
     a numeric vector, folate concentration ($\mu$g/l).
   }

This does not render sensibly in non-latex conversions, and it is what we 
have \eqn{} for.

That $ needs to be escaped is an implementation restriction that we hope 
to remove so that things like (package fields)

 	greater than or equal to 2*m where m= length( grid$x).

do not generate an error (although \code{}) markup would be appropriate 
and avoid the problem).

It is not clear if we are going to be able to do this backwards compatibly 
or not, so plese check that you are using $ correctly.  The most plausible 
scenario now is that we will have versions of Rd files with the current 
version being implicitly '1.0', and in '1.1' $ will be treated literally.

Finally, \eqn{} is for mathematics, and arbitrary markup is not allowed. 
The following (SoPhy) is causing problems:

       \eqn{\code{zlim}=\command{\link[base]{range}}(\{0,
         \theta_{s,i}\}, max(\code{h$hQThFlC}))}{\code{zlim}=\command{range}({0,
           theta_{s,i}}, max(\code{h$hQThFlC}))},


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