Hi again;
I have placed many examples in the CTFS Rd pages because my audience really
really likes lots of examples in order to understand the options available in a
functions. At this time I have set them all to \dontrun{}.
however, this isn't because the example command line with its function and
options won't work, but rather that CTFS specific datasets must exist to
have the function output mean anything (random number generation is not useful
for understanding the function output). The CTFS datasets are quite
large...20-40 MB and for some functions many other datasets need to be
available. The functions can also take quite a bit of time to run in some
cases, performing many simulations.
So, my questions are:
1. Does the R CMD check command actually run all of the examples if \dontrun{}
isn't in the Rd file? And won't this take a lot of time with real
datasets?
2. Should I consider making short versions of the datasets for the use of
\example{} ? This is trivial in some cases, but not in others as the function
only makes sense on the entire dataset. however, in those cases it is, so far,
with some of the shorter datasets.
3. Or can I just leave everything as \dontrun{} and if my audience want to
actually run a function, then can cut and paste the line out of the man page or
just type it in with their versions of the correct datasets attached?
-ph
My $0.02...> From: Pamela Hall > > Hi again; > > I have placed many examples in the CTFS Rd pages because my > audience really really likes lots of examples in order to > understand the options available in a functions. At this > time I have set them all to \dontrun{}. > > however, this isn't because the example command line with its > function and options won't work, but rather that CTFS > specific datasets must exist to have the function output mean > anything (random number generation is not useful for > understanding the function output). The CTFS datasets are > quite large...20-40 MB and for some functions many other > datasets need to be available. The functions can also take > quite a bit of time to run in some cases, performing many simulations. > > So, my questions are: > > 1. Does the R CMD check command actually run all of the > examples if \dontrun{} isn't in the Rd file? And won't this > take a lot of time with real datasets?Yes. It might take a long time, depending on the specifics of your `real data'.> 2. Should I consider making short versions of the datasets > for the use of \example{} ? This is trivial in some cases, > but not in others as the function only makes sense on the > entire dataset. however, in those cases it is, so far, with > some of the shorter datasets.I would use the minimal amount of data that's sufficient to demonstrate whatever points needed to be made in the example, and no more.> 3. Or can I just leave everything as \dontrun{} and if my > audience want to actually run a function, then can cut and > paste the line out of the man page or just type it in with > their versions of the correct datasets attached?One other possibility is to create a package vignette... Cheers, Andy> -ph > > ______________________________________________ > R-help at stat.math.ethz.ch mailing list > https://www.stat.math.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide! > http://www.R-project.org/posting-guide.html > >
On Tue, 15 Jun 2004, Pamela Hall wrote:> Hi again; > > I have placed many examples in the CTFS Rd pages because my audience > really really likes lots of examples in order to understand the options > available in a functions. At this time I have set them all to > \dontrun{}. > > however, this isn't because the example command line with its function > and options won't work, but rather that CTFS specific datasets must > exist to have the function output mean anything (random number > generation is not useful for understanding the function output). The > CTFS datasets are quite large...20-40 MB and for some functions many > other datasets need to be available. The functions can also take quite > a bit of time to run in some cases, performing many simulations. > > So, my questions are: > > 1. Does the R CMD check command actually run all of the examples if > \dontrun{} isn't in the Rd file? And won't this take a lot of time with > real datasets?Yes, they are all run. For some packages this takes a long time, for others it doesn't.> 2. Should I consider making short versions of the datasets for the use > of \example{} ? This is trivial in some cases, but not in others as the > function only makes sense on the entire dataset. however, in those > cases it is, so far, with some of the shorter datasets.If possible, it would be useful to have short versions for examples.> 3. Or can I just leave everything as \dontrun{} and if my audience want > to actually run a function, then can cut and paste the line out of the > man page or just type it in with their versions of the correct datasets > attached?You can leave things as \dontrun{}, but this should be a last resort. The automatic running of examples is really useful for catching bugs. Also, if you want examples of how to perform various tasks it may be more useful to have vignettes than examples. -thomas Thomas Lumley Assoc. Professor, Biostatistics tlumley at u.washington.edu University of Washington, Seattle