RFC: allow packages to advertise vignettes on Windows
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
}