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