[Rd] SweaveParseOptions, quoted commas, and knitr vignettes

[Yihui Xie]

Here is my understanding:

Package vignettes are built through tools::buildVignettes, which first
calls tools::pkgVignettes() to list the vignettes. Due to
loadVignetteBuilder(dir, mustwork = FALSE) in pkgVignettes(), the
vignette engine falls back to utils::Sweave if the specified vignette
builder was not found (in your case, knitr). Then because Sweave
cannot process knitr's Rnw files, the real problem goes under the
disguise of SweaveParseOptions(), which actually came from mustwork =
FALSE.

I think we discussed this issue (offline) before the non-Sweave engine
was introduced in R 3.0.0: if knitr is only required for package
vignettes, should it be specified in Depends/Imports or Suggests? The
former will make sure the vignettes always work because knitr will
always be installed, but if the user installs a prebuilt binary
package from, say, CRAN, he/she does not really need knitr to be
installed, as R will not rebuild the vignettes when installing the
binary packages. Later we decided to go with Suggests only, so that at
least R CMD check will work.

Two approaches to solve the problem:

1. either you Depends on knitr,
2. or make install.packages() also install VignetteBuilder (specified
in DESCRIPTION) when the user chooses to install from source, i.e.
install.packages(..., type = 'source')

I guess 1 is not a good choice.

Or if you want a less cryptic error message, put a code chunk like
this in your Rnw document:

<<setup, include=FALSE>>=
library(knitr)
@

I think R will emit an error that knitr was not installed, which can
be more helpful for the users to realize the real problem.

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 206-667-4385 Web: http://yihui.name
Fred Hutchinson Cancer Research Center, Seattle


On Tue, Jul 16, 2013 at 7:34 PM, Ben Bolker <bbolker at gmail.com> wrote:
>
>   I haven't figured it out entirely, but it looks like there are a
> couple of small glitches with knitr-based vignettes and
> SweaveParseOptions.
>
>   I posted the tarball of a package with a knitr vignette with (as far
> as I can tell) everything properly coded in the DESCRIPTION file
> (VignetteBuilder: knitr, Suggests: knitr) and the vignette itself
> (%\VignetteEngine{knitr::knitr}).  When Windows users (who may not
> have had knitr installed) tried to install it from source, they
> encountered an error from utils:::SweaveParseOptions .
>   The proximal source of the problem was a chunk header of the form
> <<chunkName,fig.cap="Something with a comma in it, ...">>= ; this is
> legal knitr, but doesn't make it through SweaveParseOptions because
> the function just splits on a comma without trying to check for
> nesting within quotation marks.
>   The second problem is that for some reason SweaveParseOptions was
> being called at all -- presumably it's looking at Rnw files, not
> knowing that they're really in knitr rather than Sweave format.
>
>   I'm sorry for the speculation and lack of reproducible examples
> here, but I thought it was worth commenting on.  If people are
> interested I can try to follow it up with a mini-package (one of the
> hard parts is that I can't actually reproduce the error myself -- I
> don't know if it's specific to Windows, or to not having knitr
> installed, or both ...)
>
>   Ben Bolker
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel