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

[Seth Falcon]

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.  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.
Gaah, I feel like a broken record.

What we have had with the code in Biobase is a menu of vignettes for
_attached_ packages.  Given the total number of packages that could be
installed and given the fact that running code in a vignette requires
said package to be attached, I think this makes a lot of sense [And I
think this would improve the usability of the OS X vignette browser
because the list is long, the vignettes for an individual package are
not sensibly ordered, etc].  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.

What the vignette() function does not provide for is a hook such that
a GUI can add the vignette info for attached packages.  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