[Rd] customize building package vignettes

From: Yihui Xie <xie_at_yihui.name>
Date: Fri, 19 Oct 2012 13:22:13 -0500


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

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Fri 19 Oct 2012 - 18:25:12 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Fri 19 Oct 2012 - 22:00:48 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive