24

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.

Jeroen Ooms
  • 31,998
  • 35
  • 134
  • 207
  • 7
    +1, I'd like to include static vignettes in my packages too – sckott Oct 31 '13 at 21:10
  • 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. – Dirk Eddelbuettel Oct 31 '13 at 22:24
  • 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? – sckott Oct 31 '13 at 22:28
  • Without adding a dependency on R.rsp, the following is a great solution: http://www.markvanderloo.eu/yaRb/2019/01/11/add-a-static-pdf-vignette-to-an-r-package/ – Jack Wasey May 02 '19 at 17:19

3 Answers3

15

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.

HenrikB
  • 6,132
  • 31
  • 34
  • Thanks for providing this elegant solution. Does it work for you in R 3.1.2? – krlmlr Nov 24 '14 at 10:43
  • Works for me -- seems to be a `devtools` issue. – krlmlr Nov 24 '14 at 11:15
  • 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. – HenrikB Nov 25 '14 at 15:20
  • 2
    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. – HenrikB Nov 25 '14 at 16:54
5

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.

Dirk Eddelbuettel
  • 360,940
  • 56
  • 644
  • 725
  • 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. – Camford Oxbridge Jul 14 '20 at 10:55
  • 1
    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. – Dirk Eddelbuettel Jul 14 '20 at 11:00
  • 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. – Camford Oxbridge Jul 15 '20 at 00:03
  • 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? – Camford Oxbridge Jul 18 '20 at 12:12
  • 1
    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. – Dirk Eddelbuettel Jul 18 '20 at 12:31
  • Thank you! Your answer is really helpful for me. – Camford Oxbridge Jul 19 '20 at 00:39
2

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

HenrikB
  • 6,132
  • 31
  • 34
  • I have the vague feeling that you won't be allowed more than the Rnw at a future point but no good reference. – Dirk Eddelbuettel Oct 31 '13 at 23:50
  • 1
    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. – Jeroen Ooms Nov 01 '13 at 16:35
  • 2
    I used this trick for some time, but it stopped working for me with R 3.1. – Paul Staab Jun 02 '14 at 08:42