[Rd] R CMD check for the R code from vignettes

[Duncan Murdoch]

On 03/06/2014, 12:58 AM, Yihui Xie wrote:
> Yes, I completely agree the tangle code should run without errors, if
> the package author has provided such a script. However, I think it is
> also the package author's right to choose not to provide such a
> script, for reasons that I stated in the beginning (1. redundancy; 2.
> tangle functions ignore inline expressions that should not be
> ignored).
>
> It seems that I still need to clarify it: I'm not talking about
> disabling _running_ the tangled code, but disabling _generating_ the
> code _optionally_. Unless someone is arguing that the tangled code
> _must_ be generated from vignettes, I do not think anybody in this
> discussion really has a conflict with anybody else.

I think that it's not a vignette if you can't tangle it.  Including 
\Sexpr expressions in the tangled code is the sort of option I would 
support much more than suppressing the ability to tangle.  (I don't 
think \Sexpr expressions should be included by default, but there's 
enough flexibility in the system that it shouldn't be hard to include 
them optionally.)

>
> Please also note that I do not expect R core or CRAN maintainers to do
> any extra work: package authors can easily disable tangle by
> themselves without anything special flags to R CMD build or R CMD
> check. The vignettes are still built normally (in terms of "weave"). I
> brought forward the discussion to hear the possible harm that I was
> potentially not aware of when we disable tangle for R package
> vignettes (e.g. does it affect the quality of the package?). So far I
> have not heard real harm (I admit my judgment is subjective).

Several of us have told you the real harm:  it means that users can't 
easily extract a script that replicates the computations done in the 
vignette.  That's a useful thing to be able to do.

Duncan Murdoch

>
> Regards,
> Yihui
> --
> Yihui Xie <xieyihui at gmail.com>
> Web: http://yihui.name
>
>
> On Mon, Jun 2, 2014 at 10:19 AM, Paul Gilbert <pgilbert902 at gmail.com> wrote:
>>
>>
>> On 06/02/2014 12:16 AM, Gabriel Becker wrote:
>>>
>>> Carl,
>>>
>>> I don't really have a horse in this race other than a strong feeling that
>>> whatever check does should be mandatory.
>>>
>>> That having been said, I think it can be argued that the fact that check
>>> does this means that it IS in the R package vignette specification that
>>> all
>>> vignettes must be such that their tangled code will run without errors.
>>
>>
>> My understanding of this is that the package maintainer can turn off
>> building the vignette (--no-vignettes) but R CMD check and CRAN still check
>> that the tangle code runs, and the check fails if it does not. Running the
>> tangle code can be turned off, just not by the package maintainer. You have
>> to make a special appeal to the CRAN maintainers, and give reasons they are
>> prepared to accept. I think the intention is that the tangle code should run
>> without errors. I doubt they would accept "it doesn't work" as an acceptable
>> reason. But there are reasons, like the vignette requires access to a
>> commercial database engine. Also, I think, turning this off means they just
>> do not run it regularly, in the daily checks. I don't think it necessarily
>> means the code is never tested. The testing may need to be done on machines
>> with special resources.
>>
>> Thus, --no-vignettes provides a mechanism to avoid running the tangle code
>> twice but, without special exemption, it is still run once. Some package
>> maintainers may not think of several feature of 'R CMD check' as 'aids'. I
>> think of it having more to do with maintaining some quality assurance, which
>> I think of as an aid but not a debugging aid.
>>
>> I believe the CRAN maintainers have intentionally, and successfully, made
>> disabling the running of tangled code  more trouble than it is generally
>> worth. Effectively, a package should have tangle code that runs without
>> errors.
>>
>> (Of course, I could be wrong about all this, it has happened before.)
>>
>> Paul
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>