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

[Simon Urbanek]

On May 15, 2007, at 1:57 PM, Prof Brian Ripley wrote:

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

I agree entirely.

What puzzles me: why do we need yet another way to register  
vignettes? What is wrong with vignette()?

Cheers,
Simon


>>> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>