R devel - May 2007 - RFC: allow packages to advertise vignettes on Windows

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.

+ 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
}




-- 
Seth Falcon | Computational Biology | Fred Hutchinson Cancer Research Center
http://bioconductor.org

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
> }
> 
> 
> 
>

On May 14, 2007, at 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).
>
The Mac OS X GUI already has a Vignettes-browser - just click on  
"Help" -> "Vignettes"

I don't think using a menu list is a good idea as it substantially  
limits the UI. Also as the number of packages grows, you'll end up  
which dozens of entries in the menu which will render it useless.

Cheers,
Simon

I think we've agreed about adding an option to the vignette() function 
to allow the user to choose to see all vignettes in installed packages, 
or only those that are attached.  Adding this is pretty trivial, and 
I'll put it into R-devel soon.

I'd like to set the default to show only attached packages, which would 
be consistent with the behaviour of demo() and data().  Vignettes are 
still less common than demos or data, so if I do this, I'll also change 
the "none found" message to something like

 > vignette()
no vignettes found

Use 'vignette(all = TRUE)'
to list the vignettes in all *available* packages.

Will this change to the default behaviour cause a lot of trouble for anyone?

Duncan Murdoch