Output from examples in help files - R-help

Fri, Mar 29, 2002 7:47 AM #

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