From simon.urbanek at r-project.org  Wed May 16 17:58:16 2007
From: simon.urbanek at r-project.org (Simon Urbanek)
Date: Wed, 16 May 2007 11:58:16 -0400
Subject: [Rd] RFC: allow packages to advertise vignettes on Windows
In-Reply-To: <m2lkfon5lf.fsf@ziti.fhcrc.org>
References: <m21whj2e0c.fsf@ziti.local> <464905A3.1010305@stats.uwo.ca>
	<m2fy5y27rx.fsf@ziti.local>
	<Pine.LNX.4.64.0705150745430.12894@auk.stats>
	<D79875C9-6919-4D50-BF15-43EA0F2E6FD1@r-project.org>
	<m2wsz9ofqe.fsf@ziti.fhcrc.org>
	<5C178B61-E438-4A98-9987-DB904AC3CE75@r-project.org>
	<m2lkfon5lf.fsf@ziti.fhcrc.org>
Message-ID: <93D63BF1-4A0C-4112-A498-2333EEEC9BDB@r-project.org>


On May 16, 2007, at 11:36 AM, Seth Falcon wrote:

> Simon Urbanek <simon.urbanek at r-project.org> writes:
>
>> Seth,
>>
>> we already *have* vignette registration in place [vignette()] and we
>> already *have* support in the GUIs (I'm talking e.g. about the Mac
>> GUI here which uses vignette() to build a vignettes browser).
>
> Yes, fine.  I agree that vignette() provides most of
> what is needed in terms of the implementationn details and could
> replace most of the code that I posted, but it doesn't
> mean there is nothing to do.
>
>> What you propose circumvents all the mechanisms already in place and
>> adds replicates the same functionality. I'll repeat my question: what
>> is wrong with the current approach? Why do you want to add a parallel
>> approach?
>
> What is wrong with the current approach is that, at least on Windows,
> vignettes are not as easily accessible they should be.

Ok, fine, but this is specific to the Windows GUI - it needs to be  
updated to take advantage of vignette, I' fine whit that.


>   vignette() is fine as an implementation detail for GUI  
> developers.  It is a bit silly for beginning users who will have a  
> much better chance of getting to such introductory documentation if  
> it is part of the GUI.

Definitely, so yes, fix the GUI ;). My point is that you were  
proposing vignette registration methods instead of saying 'fix the  
GUI' ;). There's nothing wrong with that if the methods need fixing,  
of course.


> What we have had with the code in Biobase is a menu of vignettes for
> _attached_ packages.

Yes, I know, I did acknowledge that it is a good idea and it's really  
easy in fact.


> [...]  A menu is not perfect, but limiting to attached packages  
> makes it a useful solution until more robust browsers etc get to  
> the top of someones TODO list.  But YMMV and what I've proposed  
> does not require your OS X GUI to change _anything_.
>
> So, as a small step, I'm trying to get vignettes for attached  
> packages to be easily accessible via the Windows GUI.  I don't care  
> all that much about the particulars -- and am certainly not  
> attached to the code that I posted.
>

But why not take the vignette() approach instead? I know, still the  
same question, I'm just trying to find you what's missing ...

> What the vignette() function does not provide for is a hook such  
> that a GUI can add the vignette info for attached packages.

Um .. I'm not quite sure I understand - all you have to do is
v=vignette(); v$results[v$results[,1] %in% search(),]
or am I missing something?

There is one thing that could be addressed I suppose - we don't have  
any hooks for GUIs in the sense that R cannot tell the GUI that  
something changed (e.g. a new package was installed). Right now each  
GUI uses system's facilities (or asynchronous checks) to learn about  
such events. This could be unified (as well as other aspects like  
e.g.  the menu access).

Cheers,
Simon

>   Comments from others in this thread suggest that there is a  
> desire that this be an opt-in feature for package authors [I don't  
> really understand this desire as it seems to me it should be a  
> feature/decision of the GUI] and again vignette() doesn't help.
>



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



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