[Rd] RFC: allow packages to advertise vignettes on Windows

[Duncan Murdoch]

On 14/05/2007 7:15 PM, Seth Falcon wrote:
> Hello,
> 
> The vignette concept, which started in Bioconductor, seems to be
> catching on.  They are supported by R CMD build/check and documented
> in the Writing R Extensions manual.  I think vignettes are a fantastic
> way to introduce new users to a package.  However, getting new users
> to realize that a vignette is available can be challenging.
> 
> For some time now, we have had a function in Biobase that creates a
> "Vignettes" menu item in the R Windows GUI and gives packages a
> mechanism to register their vignettes so that they appear on this
> menu.  I would like to see this functionality included in R so that
> there can be a standard mechanism that doesn't depend on Biobase of
> registering a package's vignettes with one of the R GUIs (currently
> only Windows is supported, but I imagine the OS X GUI could also
> implement this).
> 
> Below is the implementation we have been using.  Is there an R-core
> member I can interest in pushing this along?  I'm willing to submit a
> patch with documentation, etc.

I'm interested in making vignettes more visible.  Putting them on the 
menu is not the only way, but since you're offering to do the work, I 
think it's a good idea :-).

A few questions:

  - Should packages need to take any action to register their vignettes, 
or should this happen automatically for anything that the vignette() 
function would recognize as a vignette?

My recommendation would be for automatic installation.

  - Should it happen when the package is installed or when it is attached?

This is harder.  vignette() detects installed vignettes, which is fine 
if not many packages have them.  But I think the hope is that most 
packages will eventually, and then I think you wouldn't want the menu to 
list every package.  Maybe default to attached packages, but expose the 
function below for people who want more?

  - Should they appear in a top level Vignettes menu, or as a submenu of 
the Help menu?

I'd lean towards keeping the top level placement, since you've already 
got an audience who are used to that.

By the way, another way to expose vignettes is to have them 
automatically added to the package help topic, with links in formats 
that support them.  I think we should do that too, but I don't know if 
it'll happen soon.

Duncan Murdoch

> 
> + seth
> 
> addVigs2WinMenu <- function(pkgName) {
>     if ((.Platform$OS.type == "windows") && (.Platform$GUI == "Rgui")
>         && interactive()) {
>         vigFile <- system.file("Meta", "vignette.rds", package=pkgName)
>         if (!file.exists(vigFile)) {
>             warning(sprintf("%s contains no vignette, nothing is added to the menu bar", pkgName))
>         } else {
>             vigMtrx <- .readRDS(vigFile)
>             vigs <- file.path(.find.package(pkgName), "doc", vigMtrx[,"PDF"])
>             names(vigs) <- vigMtrx[,"Title"]
> 
>             if (!"Vignettes" %in% winMenuNames())
>               winMenuAdd("Vignettes")
>             pkgMenu <- paste("Vignettes", pkgName, sep="/")
>             winMenuAdd(pkgMenu)
>             for (i in vigs) {
>                 item <- sub(".pdf", "", basename(i))
>                 winMenuAddItem(pkgMenu, item, paste("shell.exec(\"", as.character(i), "\")", sep = ""))
>             }
>         } ## else
>         ans <- TRUE
>     } else {
>         ans <- FALSE
>     }
>     ans
> }
> 
> 
> 
>