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

[Simon Urbanek]

On May 16, 2007, at 7:38 AM, Duncan Murdoch wrote:

> On 15/05/2007 6:59 PM, Seth Falcon wrote:
>> Simon Urbanek <simon.urbanek at r-project.org> writes:
>>> 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.
>> Just to make sure we are on the same page: you are advocating for an
>> option that would be used by package developers to opt-in for their
>> vignette to be registered.
>>>> 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()?
>> Vignettes are a great form of documentation for new users.  These
>> users are more likely to be most comfortable in the GUI environment
>> and providing access to the vignettes via the GUI(s) seems like it
>> adds a lot of value.
>> I don't disagree with the assessment that a menu list isn't the  
>> worlds
>> best vignette browser interface.  But this approach has been
>> reasonably successful for the Bioconductor project to make things
>> easier for our Windows users.  Perhaps most importantly, we have code
>> that would require little modification to allow package authors to
>> register vignettes in a Vignettes menu on Windows.  I think this  
>> would
>> be an improvement over what is available now.
>> It would be great if this discussion generates interest in a more
>> robust solution; my offer of help may be limited to polishing what
>> we've been using in BioC.
>
> I think it's clear that the different GUIs should expose the  
> information in different ways.  The OSX Gui shows the list of all  
> vignettes in a very nice multi-column display, including  
> descriptions, but as far as I can see it will always show all  
> vignettes, not just those in attached packages

That is a good idea and a trivial change - I'll add it.


> , and it doesn't allow the user to drill down through the package  
> list to the list of vignettes in just one package

.. just start typing the name of the package in the search field ..

Alternative approach would be some hierarchical view, but I'm not  
very fond of it, especially because it doesn't interact well with  
dynamic searches.


> (other than by scrolling through the whole list of vignettes, which  
> are sorted alphabetically by vignette name within package name).   
> If a user has all of CRAN installed, your design would be easier to  
> use, but I wouldn't suggest that OSX should adopt it:  they should  
> just steal the good parts of it.
>
> I'd like to have a multi-column selection list in the Windows GUI,  
> but I don't think we should wait for me or someone else to program  
> that before including this improvement.  It will be easy to change  
> the look of the list later if we want to do that.
>

Indeed, and I guess you see why I don't like Seth's proposed approach  
- it is forcing a particular limited UI instead of conceptually  
providing information necessary to build a good UI.

Cheers,
Simon