[R] Should I wrap more package examples in \dontrun{} ?

[Yihui Xie]

Well, there is always trade-off. You can reinvent the whole universe
so that it is well under your control, or stand on other people's
shoulders and take the risk that they may fall one day. It is tricky
to decide how much one should depend on others.

I absolutely agree that automatic testing is a good thing. My point is
to let CRAN do everything, or the authors share some work and enjoy
some additional benefits. In either case, the testing is indeed done.

You also have a good point that package vignettes works offline, and
in my approach, it requires an additional step, which is `git clone`
(or whatever version control tools) and the whole website can be
rebuilt offline (normally via `make` or other simple commands).

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA


On Tue, Sep 3, 2013 at 12:11 PM, Duncan Murdoch
<murdoch.duncan at gmail.com> wrote:
> On 03/09/2013 1:02 PM, Yihui Xie wrote:
>>
>> But "don't use those packages that cause you trouble" implies you will
>> have to reinvent and maintain all the wheels by yourself?
>
>
> Isn't that a better alternative than having examples that don't work?
>
>>
>> What I do for long/complicated/time-consuming examples is I move them
>> to package websites or separate repositories. For example, I started
>> to use Vistat to show examples of the animation package (e.g. I write
>> http://vis.supstat.com/2013/04/buffons-needle/ in the References in
>> ?buffon.needle), and the knitr-examples repository
>> (https://github.com/yihui/knitr-examples) to serve as both a testing
>> repository and a learning repository. In these cases, it will reduce
>> the check time on CRAN, and I'll know potential problems before CRAN's
>> ticket comes. Of course, example(foo) won't show the long examples any
>> more, but I believe it is worth it, since you gain more: you can make
>> websites more visually pleasant than Rd (R documentation), you can
>> show output so users do not really have to open R and run
>> example(foo), and you have comments/interactivity/Google Analytics,
>> etc... Rd is an excellent format for documenting function arguments
>> and showing quick examples, though.
>
>
> As a user, I'd rather have examples like the ones you are discussing above
> as vignettes in the package, so that I can use them while offline, and so
> that I can have some assurance that they are tested.  As a package author,
> I'm not so sure:  it is certainly more work to produce a vignette than to
> produce a web page, but the automatic testing is a good thing.  I don't like
> having my name on documents that give bad advice, and the CRAN checks detect
> some of that.
>
> Duncan Murdoch