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.

Gratifying

why don't you just set up a tiny package and try it to see if it works? – Phionna

That is what I am trying to do... I am stuck. – Gratifying

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. – Matthaus

Answer 1

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.

Pepsinogen

Ah, so when will we see your Swv2 replacement? – Leahleahey

Whichever, I'll just count the underscores you'll sprinkle into command names :) – Leahleahey

Answer 2

(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

Phionna

Six months til 2.14.0? Isn't it usually April and October? – Leahleahey

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. – Phionna

Answer 3

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:

1. add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
2. specify VignetteBuilder: knitr in the package DESCRIPTION file
3. add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes

See also the official R documentation on that topic.

Davie