[R] Output from examples in help files

[Prof Brian D Ripley]

On Thu, 28 Mar 2002, John Fox wrote:

> Dear Frank,
>
> At 07:14 PM 3/28/2002 -0500, Frank E Harrell Jr wrote:
> >I have a large number of troff help files which are automatically
> >converted to .Rd files.  Many of these have examples which contain the
> >printed output of the examples.  This makes example(functionname) not
> >work.  Is there a way to avoid removing all this output by delimiting it
> >in some way such that the output will not appear in R-ex?  Secondly, it
> >would be nice if there was a place where output would be placed so that
> >users could check results on different platforms or after upgrading a package.
>
> I've noticed that in many cases output in help-file examples is simply
> commented out, and I've followed this practice myself; for example:

It is better to use \dontrun{} to do this. (That did not exist when a lot
of the examples you are seeing were prepared.)

>      \examples{
>      data(Kmenta)
>      summary(tsls(Q ~ P + D, ~ D + F + A, data=Kmenta))     # demand equation
>
>      ##  2SLS Estimates
>      ##
>      ##  Model Formula: Q ~ P + D
>      ##
>      ##  Instruments: ~D + F + A
>      ##
>      ##  Residuals:
>      ##      Min.   1st Qu.    Median      Mean   3rd Qu.      Max.
>      ##  -3.43e+00 -1.24e+00 -1.89e-01 -2.49e-13  1.58e+00  2.49e+00
>      ##
>      ##              Estimate Std. Error t value  Pr(>|t|)
>      ##  (Intercept)  94.6333    7.92084  11.947 1.076e-09
>      ##  P            -0.2436    0.09648  -2.524 2.183e-02
>      ##  D             0.3140    0.04694   6.689 3.811e-06
>      ##
>      ##  Residual standard error: 1.9663 on 17 degrees of freedom
>
>      . . .
>
>      }
>
> Of course, you'll probably have to add the #'s manually. (I agree that it
> would be nice if output were handled explicitly in .Rd files.)

To do that needs much more markup, including have separate \example{}
sections inside \examples{}.

A much better way to achieve `users could check results on different
platforms or after upgrading' is to use a tests directory in the package,
which R CMD check will run and compare the results to the reference output.
See e.g. rpart and nlme for examples.

Brian

-- 
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 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._