[R] Output from examples in help files

[Warnes, Gregory R]

I would also find it usefult to be able to easily include the output of
commands in the example section by using a markup command.

Something like:

\examples{
     x <- rnorm(1000)
     quants <- quantcut( x )
     table(quants)     y _ rnorm(100)
     \output{
     quants
       [-3.64,-0.651] (-0.651,-0.0353]  (-0.0353,0.615]     (0.615,2.69] 
                  250              250              250              250 
     }
}

Which might be rendered something like

     y _ rnorm(100)
     x _  cut(rnorm(100, mean=y, sd=0.25),c(-4,-1.5,0,1.5,4))
     table(x)
     # Output: 
     #      quants
     #       [-3.64,-0.651] (-0.651,-0.0353]  (-0.0353,0.615]
(0.615,2.69] 
     #                  250              250              250
250 
     #

In plain text, or with suitable font/highlighting changes in HTML / LaTeX.  

-Greg

> -----Original Message-----
> From: John Fox [mailto:jfox at mcmaster.ca]
> Sent: Friday, March 29, 2002 8:18 AM
> To: Prof Brian D Ripley
> Cc: Frank E Harrell Jr; rhelp
> Subject: Re: [R] Output from examples in help files
> 
> 
> 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
> _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._.
> _._._._._._._._._
> 


LEGAL NOTICE
Unless expressly stated otherwise, this message is confidential and may be privileged. It is intended for the addressee(s) only. Access to this E-mail by anyone else is unauthorized. If you are not an addressee, any disclosure or copying of the contents of this E-mail or any action taken (or not taken) in reliance on it is unauthorized and may be unlawful. If you are not an addressee, please inform the sender immediately.
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._