Hi Kevin, Personally I also avoid code that have side effects in the inline expressions, but I think there are legitimate use cases in which inline expressions have side effects. This discussion was motivated by Carl's knitcitations package, as well as another question on StackOverflow (http://stackoverflow.com/q/23927325/559676).
I'm aware of the distinction between the original literate programming paradigm and the one in R (that is why I said "literate programming in R" instead of "literate programming in general"). In R, weave actually does what both weave and tangle do in the original paradigm -- there is no need to tangle the document to get the computer code so that we can execute it. To Carl: I agree that it is a little extreme to drop tangle entirely, so I think at least knitr::purl() will stay there in the foreseeable future. I tend to adopt Henrik's idea, i.e., to provide vignette engines that just ignore tangle. At the moment, it seems R CMD check is comfortable with vignettes that do not have corresponding R scripts, and I hope these R scripts will not become mandatory in the future. Thanks everyone for your comments! Regards, Yihui -- Yihui Xie <xieyi...@gmail.com> Web: http://yihui.name On Fri, May 30, 2014 at 8:21 AM, Kevin Coombes <kevin.r.coom...@gmail.com> wrote: > Hi, > > Unless someone is planning to change Stangle to include inline expressions > (which I am *not* advocating), I think that relying on side-effects within > an \Sexpr construction is a bad idea. So, my own coding style is to restrict > my use of \Sexpr to calls of the form > \Sexpr{show.the.value.of.this.variable}. As a result, I more-or-less believe > that having R CMD check use Stangle and report an error is probably a good > thing. > > There is a completely separate questions about the relationship between > Sweave/Stangle or knit/purl and literate programming that is linked to your > question about whether to use Stangle on vignettes. The underlying model(s) > in R have drifted away from Knuth's original conception, for some good > reasons. > > The original goal of literate programming was to be able to explain the > algorithms and data structures in the code to humans. For that purpose, it > was important to have named code chunks that you could move around, which > would allow you to describe the algorithm starting from a high level > overview and then drilling down into the details. From this perspective, > "tangle" was critical to being able to reconstruct a program that would > compile and run correctly. > > The vast majority of applications of Sweave/Stangle or knit/purl in modern R > have a completely different goal: to produce some sort of document that > describes the results of an analysis to a non-programmer or > non-statistician. For this goal, "weave" is much more important than > "tangle", because the most important aspect is the ability to integrate the > results (figures, tables, etc) of running the code into the document that > get passed off to the person for whom the analysis was prepared. As a > result, the number of times in my daily work that I need to explicitly > invoke Stangle (or purl) explicitly is many orders of magnitude smaller than > the number of times that I invoke Sweave (or knitr). > > -- Kevin > > > > On 5/30/2014 1:04 AM, Yihui Xie wrote: >> >> Hi, >> >> Recently I saw a couple of cases in which the package vignettes were >> somewhat complicated so that Stangle() (or knitr::purl() or other >> tangling functions) can fail to produce the exact R code that is >> executed by the weaving function Sweave() (or knitr::knit(), ...). For >> example, this is a valid document that can pass the weaving process >> but cannot generate a valid R script to be source()d: >> >> \documentclass{article} >> \begin{document} >> Assign 1 to x: \Sexpr{x <- 1} >> <<>>= >> x + 1 >> @ >> \end{document} >> >> That is because the inline R code is not written to the R script >> during the tangling process. When an R package vignette contains >> inline R code expressions that have significant side effects, R CMD >> check can fail because the tangled output is not correct. What I >> showed here is only a trivial example, and I have seen two packages >> that have more complicated scenarios than this. Anyway, the key thing >> that I want to discuss here is, since the R code in the vignette has >> been executed once during the weaving process, does it make much sense >> to execute the code generated from the tangle function? In other >> words, if the weaving process has succeeded, is it necessary to >> source() the R script again? >> >> The two options here are: >> >> 1. Do not check the R code from vignettes; >> 2. Or fix the tangle function so that it produces exactly what was >> executed in the weaving process. If this is done, I'm back to my >> previous question: does it make sense to run the code twice? >> >> To push this a little further, personally I do not quite appreciate >> literate programming in R as two separate steps, namely weave and >> tangle. In particular, I do not see the value of tangle, considering >> Sweave() (or knitr::knit()) as the new "source()". Therefore >> eventually I tend to just drop tangle, but perhaps I missed something >> here, and I'd like to hear what other people think about it. >> >> Regards, >> Yihui >> -- >> Yihui Xie <xieyi...@gmail.com> >> Web: http://yihui.name ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
