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

[Prof Brian Ripley]

On Mon, 14 May 2007, Seth Falcon wrote:

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

I do think this should be optional, and preferably an option that people 
have to opt in for.

Some sort of vignette browser that packages can register with would in my 
view be better, and that could have a single menu entry.  Menus can easily 
get swamped.

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

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595