[R] Output from examples in help files

[John Fox]

Dear Brian,

At 07:02 AM 3/29/2002 +0000, Prof Brian D Ripley wrote:
>On Thu, 28 Mar 2002, John Fox wrote:
>
> > 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.)

Unless I've missed something, the problem with using \dontrun{} for all of 
the examples (assuming that all show output) is that none of the examples 
would be run. As well, with the output not differentiated visually from the 
input, it might be hard for the reader to distinguish the two.

> >
> > 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{}.

I personally wouldn't find it onerous to put output within something like 
\example{} or \output{} -- it would be less work than adding #'s.

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

I agree that this is better for checking that the package is functioning 
properly. When I read help pages, however, I find that I often copy 
examples and paste them at the command prompt to see the result. Having the 
output in the help file would make this unnecessary. Not a large point, of 
course. In general, I find the package-building tools, including for 
documentation, very well thought out.

Thanks,
  John

-----------------------------------------------------
John Fox
Department of Sociology
McMaster University
Hamilton, Ontario, Canada L8S 4M4
email: jfox at mcmaster.ca
phone: 905-525-9140x23604
web: www.socsci.mcmaster.ca/jfox
-----------------------------------------------------

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