14

I want to include a pre-compiled PDF as a vignette in a R package. The PDF is not generated via Sweave. Without a .Rnw to process, there is no \VignetteIndexEntry to cause the usual automatic generation of index.html and Meta/vignette.rds.

I created an index.html in inst/doc that is copied into doc during installation. This is corrected linked from the main package help page. However, when I load the package and execute browseVignettes("MyPackage"), I get

No vignettes found by browseVignettes("MyPackage")

This makes sense, because R apparently has no way to know that the package has a vignette. The installed package has no Meta/vignette.rds file. Can I somehow get my PDF to appear with browseVignettes()?

pdfpages

I'm familiar with the approach taken by the mosaic package, which is to use pdfpages to include the entire PDF. While clever, I feel like there should be a better way that avoids the proliferation of files.

Nicholas Horton
  • 19
  • 1
kmm
  • 6,045
  • 7
  • 43
  • 53
  • possible duplicate of [Using a static (prebuilt) PDF vignette in R package](http://stackoverflow.com/questions/19716498/using-a-static-prebuilt-pdf-vignette-in-r-package) – krlmlr Nov 24 '14 at 10:11

3 Answers3

9

Right after Yihui....

Make a fake Rnw that looks like this:

%\VignetteIndexEntry{User manual}
\documentclass{article}
\begin{document}
\end{document}

And put it in inst/doc along side your precompiled vignette and you will be all set.

Bryan Hanson
  • 6,055
  • 4
  • 41
  • 78
  • Does this obviate the need for a Makefile? – Josh O'Brien Oct 29 '12 at 20:47
  • This approach seems to work perfectly. I thought that R might clobber the pre-existing PDF when it processed the Rnw, but it didn't. – kmm Oct 29 '12 at 20:49
  • 1
    I don't use a Makefile, something I need to learn I suppose. You just drop that text in, and separately prepare your vignette. When you run 'R CMD CHECK...` it works. I can't remember where I found this trick, it's not in SO. But it's not original to me. – Bryan Hanson Nov 02 '12 at 10:36
  • 1
    I came across this trick on [Rd] while trying to find solutions to this exact question today. [Henrik Bengtsson](https://stat.ethz.ch/pipermail/r-devel/2012-April/063846.html) – Benjamin Aug 09 '14 at 11:05
  • @Benjamin Excellent, good to give the proper credit. Thanks for providing the link. – Bryan Hanson Aug 09 '14 at 12:01
  • this does not work for me in R 3.3.2 where an R CMD check halts after a "system cannot find the file specified" error. – pdb Dec 15 '16 at 23:06
  • Double check everything. I run checks on files like this almost daily. – Bryan Hanson Dec 15 '16 at 23:31
  • yeah, still not working. I have both the fake file and the pdf in inst/doc and R CMD check says that the vignette source in inst/doc is missing from the vignettes directory. Does it matter what the VignetteBuilder: is in DESCRIPTION? I'm using knitr. Do I need a dummy knitr file instead of this dummy Sweave file? – pdb Dec 16 '16 at 05:30
  • It does matter as so some other settings; check out section 1.4.2 "Non-Sweave vignettes" in *Writing R Extensions*. Sounds like something small is missing or wrong in your settings, you'll find it! – Bryan Hanson Dec 16 '16 at 12:17
  • the only thing I see is that it says to include a makefile, which you say you don't use. Maybe I have the files in the wrong spots. I have the .pdf in both vignettes/ and inst/doc and the .Rnw file in just vignettes/, is that right? – pdb Dec 16 '16 at 16:29
  • You are running `BUILD` first, and running `CHECK` on the tarball, correct? And if you temporarily take out all things related to the vignette, it builds and checks correctly? If so, try adding one thing back at a time. Maybe try putting in a trivial test vignette and see if that works (i.e., use the dummy file above but put Hello in it). And are you using RStudio? That might change things substantially. – Bryan Hanson Dec 16 '16 at 17:46
  • I found another solution, but I think it could be helpful if you edited the answer to indicate exactly what file you put where. – pdb Dec 16 '16 at 20:37
2

R definitely needs a better way to deal with vignettes: http://comments.gmane.org/gmane.comp.lang.r.devel/31967 Before my proposal is approved and implemented, we still have to live with the dark voodoo of Makefile. For example, you can put a fake.Rnw and a real.pdf under inst/doc, and mv real.pdf fake.pdf in the Makefile. In fake.Rnw, you just follow the rule of \VignetteIndexEntry{}.

Yihui Xie
  • 28,913
  • 23
  • 193
  • 419
  • Just to be clear, does this mean you put a file named `Makefile` and containing the single line `mv real.pdf fake.pdf` in the top of your package source directory? – Josh O'Brien Oct 29 '12 at 20:46
1

The mosaic package now apparently uses the R.rsp package which has an "asis" driver that allows including an existing file and creating the VignetteIndexEntry. This looks much less like a hack than using pdfpages or a dummy .Rnw file (which doesn't seem to work anymore in R 3.1).

Example: For a file V1MinimalR.pdf, there is a corresponding V1MinimalR.pdf.asis file with the following contents:

%\VignetteIndexEntry{Minimal R for Intro Stats}
%\VignetteEngine{R.rsp::asis}

The DESCRIPTION contains (among others) the following:

Suggests: R.rsp
VignetteBuilder: knitr, R.rsp

This is also detailed in this answer by Henrik Bengtsson, the author of the R.rsp package.

Community
  • 1
  • 1
krlmlr
  • 25,056
  • 14
  • 120
  • 217