Using a static (prebuilt) PDF vignette in R package

Question

What is the proper way, to include a static PDF file as a "vignette" in a CRAN package as of R 3.0?

The trick described in this document of using an empty stub Rnw does not seem to work in R 3.0. The document suggests that there is now a better way based on \VignetteEngine{} but it's not quite clear how this works for static PDF files.

Answer 1

With R.rsp (>= 1.19.0) you can include a static PDF 'vignettes/main.pdf' by adding a tiny 'vignettes/main.pdf.asis' text file that contains:

%\VignetteIndexEntry{My amazing package}
%\VignetteEngine{R.rsp::asis}

and make sure to have:

Suggests: R.rsp
VignetteBuilder: R.rsp

in your package's DESCRIPTION file. This also works for static HTML vignettes. This is also explained in one of the R.rsp vignettes.

Answer 2

This works with a plain LaTeX trick as described in in this blog post.

I recently switched to doing this with the current R version (i.e. now 3.6.0), see this wrapper .Rnw file which contains just:

\documentclass{article}
\usepackage{pdfpages}
%\VignetteIndexEntry{Using Annoy in C++}
%\VignetteKeywords{Rcpp, Annoy, R, Cpp, Approximate Nearest Neighbours}
%\VignettePackage{RcppAnnoy}

\begin{document}
\includepdf[pages=-, fitpaper=true]{UsingAnnoyInCpp.pdf}
\end{document}

The advantage is that this uses Sweave for a completely traditional vignette build, and imposes no additional dependencies whatsover.

Answer 3

UPDATE 2014-06-08: For a better solution to including static PDFs and HTML files in an R package, see my other answer in this thread on how to use R.rsp (>= 0.19.0) and its R.rsp::asis vignette engine.

All you need is a <name>.Rnw file with a name matching your static <name>.pdf file, e.g.

vignettes/
  static.pdf
  static.Rnw

where <name>.Rnw (here static.Rnw) is a minimal valid Sweave file, e.g.

%\VignetteIndexEntry{<title to be displayed on the R vignette index page>}
\documentclass{article}
\begin{document}
\end{document}

This vignette source file (<name>.Rnw) tricks R CMD build to build it, i.e. R's tools::buildVignettes() will first Sweave <name>.Rnw into <name>.tex as usual. However, due to how buildVignettes() is designed it will detect our static <name>.pdf file as already being created by the Sweave engine and therefore it will not compile that dummy TeX file into a PDF file (which would overwrite our static file).

What is important to understand is that (i) vignettes are "build" during R CMD build, (ii) and when built they are copied over to the inst/doc/ directory (created if missing) of the built package. Also, (iii) the vignettes/ directory will not be part of the build package, i.e. <pkgname>_<version>.tar.gz file. So, make sure to look in inst/doc/.

So, to be clear here, using a dummy <name>.Rnw could be considered a hack that may break if someone decides to prevent against this strategy. However, if that happens, it is fully possible to create a non-Sweave vignette engine which sole purpose is to compile a <name>.pdf file into a ... <name>.pdf file. This is valid and possible due to the non-Sweave support added in R (>= 3.0.0). I've been considering adding such engine to the R.rsp package, e.g. \VignetteEngine{R.rsp::StaticPDF}. With that you would not even have to have that dummy Rnw file - only the PDF file.

Hope this helps