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

[Seth Falcon]

Duncan Murdoch <murdoch at stats.uwo.ca> writes:
> 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 :-).

Excellent :-)

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

That seems ok to me.  Currently, we have a system that requires
package authors to register their vignette in .onAttach (more on that
below).  I can't really think of a case where a package provides
vignettes and doesn't want them easily accessible to new users in a
GUI environment.

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

My feeling is that this is only appropriate for attached packages.  As
you point out, adding an entry for every installed package could
create a cluttered menu (and present implementation challenges to
avoid slowness).  I also think that packages that get loaded via other
packages name spaces should remain in stealth mode.  

There is another reason to only list vignettes for attached packages.
One of the primary uses of a vignette is to allow the user to work
through an example use case interactively.  This requires the package
to be attached in almost all cases.

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

Sounds good.

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

Also sounds good, but one thing at a time, I guess.

If there is some agreement about vignettes being automatically added
and that this only happens when a package is attached, then I can look
into modifying the existing function to handle this.

+ seth

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