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.

Puttier

+1, I'd like to include static vignettes in my packages too – Hamm

I wondered about that too but as I read the manual and the tea leaves, it is moving towards all vignettes/ with even stricter enforcement in the future. – Lisbethlisbon

Hmmm. In that case, I think I may just have links out to web pages with the tutorials since most of my packages make API calls to the web. Unless there is some important reason to have vignettes actually inside pkgs? – Hamm

Without adding a dependency on R.rsp, the following is a great solution: markvanderloo.eu/yaRb/2019/01/11/… – Polygraph

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.

Koffman

Thanks for providing this elegant solution. Does it work for you in R 3.1.2? – Leventhal

Works for me -- seems to be a devtools issue. – Leventhal

Your welcome - I'm glad you like it. Yes all of R.rsp's vignette engines works with older versions of R too. They work out of the box with R (>= 3.0.0). For them to also work with R (< 3.0.0) you have to add a fallback solution which is explained in one of the R.rsp vignettes. – Koffman

Just a heads up: In the next release(*) of R.rsp, there will also be a \VignetteEngine{R.rsp::tex} vignette engine that takes a static LaTeX file and compiles it into a PDF vignette, which should provide a more reproducible package. (*) This comment will be updated when it is released. – Koffman

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.

Lisbethlisbon

I put a '%' as %\includepdf[pages=-, fitpaper=true]{UsingAnnoyInCpp.pdf} then, comiplation of pdf works and passed throgh R CMD check . Without %, error oocured in compilation of pdf. – Bantustan

Well that one line is the whole point of this as it includes the file UsingAnnoyInCpp.pdf, which is my preprocessed file. You need to give it your file which has to exists. – Lisbethlisbon

Yes, I changed the pdf name. Because s.Rnw, I use % \includepdf[pages=-, fitpaper=true]{s.pdf} .... Yesterday, the error occured but today, it works, sorry and thank you. – Bantustan

The following two codes also can be editted freely ? %\VignetteIndexEntry{　xxxx　　} %\VignetteKeywords{　　yyyy　} On the other hand, \usepackage{pdfpages} and %\VignettePackage{RcppAnnoy} should not be changed, is it correct? – Bantustan

Yes. The first is actually important, the second one mostly ignored. \usepackage{} is an instruction to LaTeX you must keep to use the trick; and the last one needs to be changed to your package as thie example I quoted came from my RcppAnnoy package. – Lisbethlisbon

Thank you! Your answer is really helpful for me. – Bantustan

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

Koffman

I have the vague feeling that you won't be allowed more than the Rnw at a future point but no good reference. – Lisbethlisbon

I couldn't get this to work on R 3.0 without manually modifying the package.tar.gz. The problem is that, as you describe, during R CMD build the pdf gets moved to /inst/doc. However, the /vignettes/static.Rnw does get included in the source package and will be rebuild during R CMD check at which point it will fail because it doesn't generate the pdf file. – Puttier

I used this trick for some time, but it stopped working for me with R 3.1. – Carminacarminative