R -- Vignettes that are not made by Sweave possible?

Question

Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?

I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.

The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.

Any hints are appreciated.

why don't you just set up a tiny package and try it to see if it works? — Ben Bolker, Jul 09 '11 at 12:50
FWIW, `?vignette` says that `Currently, only PDF versions of vignettes can be viewed.` Everything else is there for the user to find on his or her own. In that case, `browseVignettes` may be of help. — Roman Luštrik, Jul 09 '11 at 13:35

krlmlr · Answer 1 · 2013-12-11T15:29:38.147

This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.

Instructions to use knitr as vignette engine boil down to:

add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)

specify VignetteBuilder: knitr in the package DESCRIPTION file

add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes

See also the official R documentation on that topic.

score 5 · Accepted Answer · answered Jul 09 '11 at 13:47

5

I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.

answered Jul 09 '11 at 13:47

hadley

102,019
32
183
245

3

Ah, so when will we see your Swv2 replacement? – Dirk Eddelbuettel Jul 09 '11 at 13:55
1

Whichever, I'll just count the underscores you'll sprinkle into command names :) – Dirk Eddelbuettel Jul 09 '11 at 21:33

Ben Bolker · Answer 3 · 2012-05-31T07:51:15.780

(Cross-posted from a response I just left on R-help:)

As a workaround, you could include your own xvignette function in your package: see below. It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your package ...

xvignette <- function(vname,pkg,ext="pdf") {
   vname <- paste(vname,ext,sep=".")
   fn <- system.file("doc",vname,package=pkg)
   if (nchar(fn)==0) stop("file not found")
   utils:::print.vignette(list(pdf=fn))
   invisible(fn)
 }

You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.

You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...

Brian Ripley also mentioned in his response to the question that:

At present vignette() means Sweave documents, as only they have metadata like titles. This is planned to be changed soon.

... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)

edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)

edit 2: And

here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package

I guess so. I was thinking about the recent 2.13.1 release and forgetting that it's 6 months between .0 releases, not point releases. So only 2.5 months. — Ben Bolker, Jul 14 '11 at 19:30

R -- Vignettes that are not made by Sweave possible?

3 Answers3