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

Mon Jun 2 07:06:28 CEST 2014

On 02/06/2014, 1:41 PM, Carl Boettiger wrote:
> Thanks both for the replies.
>
> Duncan, I'm sorry if I wasn't clear.  I am indeed writing a vignette using
> Sweave (knitr actually), and I want it to be a vignette. I'm well aware
> that I can dodge these tests as you suggest, or through other ways, but I'm
> not trying to dodge them.  R CMD check is running both knit and
> tangle+source on it, and I do not understand why the latter is necessary
> when the code is already run by the former.  Is there a good reason for
> checking an R vignette in this seemingly redundant fashion?
>
> Gabe, I see your point but surely you can agree that is a rather obtuse way
> to enforce that behavior. I don't recall seeing anything in the R
> extensions manual documenting that Sweave files must meet this constraint
> in order to be considered valid vignettes.  I also believe there are valid
> use cases for side-effects of inline chunk options (my example being
> dynamic references).  While it is easy to hack a vignette to meet this
> constraint (e.g. replicating inline calls with non-displayed chunk), that
> seems poor form.
>
> I think Yihui has made a good case that there is no reason for R CMD check
> to be running weave/knit and source, and I haven't seen any replies trying
> to explain to the contrary why this is a reasonable thing for the automated
> check to be doing.

You haven't been reading very carefully.  I saw several:  mine, Martin 
Morgan's, Kasper Daniel Hansen's.

Duncan Murdoch
>
> Cheers,
>
> Carl
>
>
> On Sun, Jun 1, 2014 at 9:16 PM, Gabriel Becker <gmbecker at ucdavis.edu> 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.
>>
>> ~G
>>
>>
>> On Sun, Jun 1, 2014 at 8:43 PM, Carl Boettiger <cboettig at gmail.com> wrote:
>>
>>> Yihui, list,
>>>
>>> Focusing the behavior of R CMD check, the only reason I have seen put
>>> forward in the discussion for having check tangle and then source as well
>>> as knit/weave the very same vignette is to assist the package maintainer in
>>> debugging R errors vs pdflatex errors.  As tangle (and many other tools)
>>> are already available to an author needing extra help debugging, and as the
>>> error messages are usually clear on whether errors come from the R code or
>>> whatever format compiling (pdflatex, markdown html, etc), this seems like a
>>> poor reason for R CMD check to be wasting time doing two versions of almost
>>> (but not literally) the same check.
>>>
>>> As has already been discussed, it is possible to write vignettes that can
>>> be Sweave'd but not source'd, due to the different treatments of inline
>>> chunks.  While I see the advantages of this property, I don't see why R CMD
>>> check should be enforcing it through the arbitrary mechanism of running
>>> both Sweave and tangle+source. If that is the desired behavior for all
>>> Sweave documents it should be in part of the Sweave specification not to be
>>> able to write/change values in inline expressions, or part of the tangle
>>> definition to include inline chunks.  I any event I don't see any reason
>>> for R CMD check doing both.  Perhaps someone can fill in whatever I've
>>> overlooked?
>>>
>>> Carl
>>>
>>>
>>> On Sat, May 31, 2014 at 8:17 PM, Yihui Xie <xie at yihui.name> wrote:
>>>
>>>> 1. The starting point of this discussion is package vignettes, instead
>>>> of R scripts. I'm not saying we should abandon R scripts, or all
>>>> people should write R code to generate reports. Starting from a
>>>> package vignette, you can evaluate it using a weave function, or
>>>> evaluate its derivative, namely an R script. I was saying the former
>>>> might not be a bad idea, although the latter sounds more familiar to
>>>> most R users. For a package vignette, within the context of R CMD
>>>> check, is it necessary to do tangle + evaluate _besides_ weave?
>>>>
>>>> 2. If you are comfortable with reading pure code without narratives,
>>>> I'm totally fine with that. I guess there is nothing to argue on this
>>>> point, since it is pretty much personal taste.
>>>>
>>>> 3. Yes, you are absolutely correct -- Sweave()/knit() does more than
>>>> source(), but let me repeat the issue to be discussed: what harm does
>>>> it bring if we disable tangle for R package vignettes?
>>>>
>>>> Sorry if I did not make it clear enough, my priority of this
>>>> discussion is the necessity of tangle for package vignettes. After we
>>>> finish this issue, I'll be happy to extend the discussion towards
>>>> tangle in general.
>>>>
>>>> Regards,
>>>> Yihui
>>>> --
>>>> Yihui Xie <xieyihui at gmail.com>
>>>> Web: http://yihui.name
>>>>
>>>>
>>>> On Sat, May 31, 2014 at 9:20 PM, Gabriel Becker <gmbecker at ucdavis.edu>
>>>> wrote:
>>>>>
>>>>>
>>>>>
>>>>> On Sat, May 31, 2014 at 6:54 PM, Yihui Xie <xie at yihui.name> wrote:
>>>>>
>>>>>> I agree that fully evaluating the code is valuable, but
>>>>>> it is not a problem since the weave functions do fully evaluate the
>>>>>> code. If there is a reason for why source() an R script is preferred,
>>>>>>
>>>>>> I guess it is users' familiarity with .R instead of .Rnw/.Rmd/...,
>>>>>
>>>>>
>>>>> It's because .Rnw and Rmd require more from the user than .R. Also,
>>>> this
>>>>> started with vignettes but you seem to be talking more generally. If
>>>> so, I
>>>>> would point out that not all R code is intended to generate reports,
>>>> and
>>>>> writing pure R code that isn't going to generate a report in an
>>>> .Rnw/.Rmd
>>>>> file would be very strange to say the least.
>>>>>
>>>>>
>>>>>>
>>>>>> however, I guess it would be painful to read the pure R script tangled
>>>>>> from the source document without the original narratives.
>>>>>
>>>>>
>>>>> That depends a lot on what you want. Reading an woven article/report
>>>> that
>>>>> includes code and reading code are different and equally valid
>>>> activities.
>>>>> Sometimes I really just want to know what the author actually told the
>>>>> computer to do.
>>>>>
>>>>>>
>>>>>>
>>>>>> So what do we really lose if we turn off tangle? We lose an R script
>>>>>> as a derivative from the source document, but we do not lose the code
>>>>>> evaluation.
>>>>>
>>>>>
>>>>> We lose *isolated* code evaluation. Sweave/knit have a lot more moving
>>>>> pieces than source/eval do. Many of which are  for the purpose of
>>>> displaying
>>>>> output, rather than running code.
>>>>>
>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>
>>>
>>>
>>>
>>> --
>>> Carl Boettiger
>>> UC Santa Cruz
>>> http://carlboettiger.info/
>>>
>>
>>
>>
>> --
>> Gabriel Becker
>> Graduate Student
>> Statistics Department
>> University of California, Davis
>>
>
>
>