[Rd] customize building package vignettes

[Yihui Xie]

Hi,

I mentioned this at useR! 2012 but I guess the relevant R core members
were not there (presumably Fritz, Duncan and Brian), so I'm making
this wishlist again:

Currently package vignettes have to be processed through Sweave, which
is too restrictive since several add-on packages aiming to improve or
extend Sweave have appeared (e.g. cacheSweave, pgfSweave, R.rsp,
highlight, knitr, ...). The common hack that package authors use, as
far as I can see, is the Makefile. One example is at
https://github.com/yihui/knitr/blob/master/inst/doc/Makefile

Although this hack works well for some cases, it is potentially
problematic in two aspects:

1. The vignette has to be processed by Sweave anyway, and it is a
waste of time because it will be processed by another package later in
the Makefile;
2. The syntax of the vignette may not be compatible with Sweave, so
Sweave can run into errors (e.g. <<eval = if (foo > 5) TRUE else
FALSE>>=); there is a darker hack for this but we really hate hacks;

Vignettes are extremely valuable resources for R packages, and I
really wish there could be a natural way for package developers to
compile vignettes using a customized routine. For example, introduce a
build.R under inst/doc or vignettes/ which takes care of building the
vignettes; if it does not exist, just call Sweave() as the default
approach.

Here is one discussion about a package on Bioconductor which should
strengthen my proposal:
http://grokbase.com/t/r/bioc-devel/129vxrxabm/to-use-knitr-how-to-write-the-right-makefile-for-bioconductor-devel-and-released-branch

There are further advantages if package authors are not restricted to
Sweave; the corrplot package is an example of building an HTML
vignette which could be easier for authors who are not familiar with
LaTeX and they can also distribute the vignette on the web easily.
See:

if (!require('corrplot')) install.packages('corrplot')
help(package = 'corrplot', help_type = 'html')

I have talked to some R core and Bioc core members offline, and this
seems to be a reasonable request. I will be grateful if this can be
considered and implemented in the future.

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 515-294-2465 Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA