From xie at yihui.name  Sun Jun  1 05:17:43 2014
From: xie at yihui.name (Yihui Xie)
Date: Sat, 31 May 2014 22:17:43 -0500
Subject: [Rd] R CMD check for the R code from vignettes
In-Reply-To: <CADwqtCNQEAz==L4fSomQt+Ayw6wSo61-uM=xN_9K26K1XRoFwQ@mail.gmail.com>
References: <CANROs4dyoXEUEzouGTsL9sHCMM8RcjYWw9584SUAEYfGntPrFg@mail.gmail.com>
	<538885F3.8020807@gmail.com>
	<CANROs4eect+qAvXTLEzPhM=X2Eg5R0T-DCUBO6=VDfBFVJNCuQ@mail.gmail.com>
	<CADwqtCN2XixFy0H43BeFMU7R_p+sQCaOHBU5W6tXn7Ng7pP1pA@mail.gmail.com>
	<CANROs4c=x7BNDWJ7ObS5pB36+NBGzVmTmN7-94t8T+dowcEA5A@mail.gmail.com>
	<538A63C6.5030201@fhcrc.org>
	<CANROs4cM=q0isYqUO6eg2vWjT2HieUy996u7HtS8_deydFa-8g@mail.gmail.com>
	<CADwqtCNQEAz==L4fSomQt+Ayw6wSo61-uM=xN_9K26K1XRoFwQ@mail.gmail.com>
Message-ID: <CANROs4cuHbSTeNXgBuWFAhpHGMVdGLsAs5gFH+8s=HCq8NYiwQ@mail.gmail.com>

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.
>



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