[Rd] RFC: allow packages to advertise vignettes on Windows
Duncan Murdoch
murdoch at stats.uwo.ca
Tue May 15 02:58:11 CEST 2007
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
> }
>
>
>
>
More information about the R-devel
mailing list