[R-pkg-devel] questions about \dontrun{} etc.

[Paul Johnson]

I think Ben has a good question and I have a related followup.

On Thu, Sep 6, 2018 at 2:07 PM Ben Bolker <bbolker using gmail.com> wrote:
>  * My preference would be for using \dontrun{} universally (consistent,
> readable, mostly avoids accidental runs), but this goes against
> (informal?) CRAN policy
>
>  * universal \donttest{} doesn't seem to do what I want, since I *do*
> want to avoid users having to run long examples
>
>   * commenting (with something like "original model:" to make it clearer
> that it's not a commented-out example) is even better for avoiding
> accidental runs (harder to accidentally cut-and-paste, if doing that
> rather than using example()), but less readable.
>
>   * putting slow model fits in \dontrun{} and letting fast model fits be
> executed does what CRAN asks and helps avoiding example-drift, but is
> less consistent -- and I can't be sure that a model fit won't take much
> longer on one of CRAN's test machines ...
>
>   Thoughts?
>
>   cheers
>    Ben Bolker

Suppose author creates code in an if/then construct.  It saves a copy
of a long running calculation in the package.  In the example code,
make it obvious how to run it, or simply load it from disk, like

RUNLONGCALCULATIONS <- FALSE
if (RUNLONGCALCULATIONS){
    ## step 1
    ## ...code that runs and saves the output object
} else {
   ## step 2
   result <- readRDS( ...load the output object that is distributed in
the package...)
}

To my eye, this is a good compromise between transparency and package
testing speed. A user can see the code that was actually run. There is
no danger it will run by accident. In other words, the code that might
run is not commented out, but it is nested in an if/then.

Do you dis/like this idea?

The obvious problem: by avoiding \dontrun and \donttest, it
circumvents the CRAM example-checking apparatus.

But now I have a more suspicious version of the idea.

The package author uploads results from step 1 to a website and the
package example code downloads the result file. This is done to avoid
the GB limit on the package. I have seen this approach used on
vignettes already, where larger documents are placed on a website and
in-package vignettes are just lists of links.

PJ