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

[Gabor Grothendieck]

Just a few other points:

- vignettes are potentially of interest even before you download the package
in order to decide whether the package is of interest.  The discussion so far
here does not address that.  If I am interested in mypackage I will typically
google for
  CRAN mypackage
and then look at the vignette from that page prior to downloading the
package.  Alternately I might click the package name in the contributed
package list on the R Web site.

- probably in most cases one identifies a package first and only then
requests its vignette.  I guess one could try to locate packages based
on whether or not they have vignettes but I think that that would be
less likely.

- one can currently get to vignettes via the Windows menu and subsequent
HTML via:
1. From the R Help menu choose the "Html help" entry on it
    [ or issue the R command: help.start() ]
2. click on Packages
3. click on the package of interest
4. click on "overview"
5. click on the vignette.

This sequence is a bit long.  Perhaps there just needs to be a menu entry
that goes directly to the package list from the menu. Also the word
"overview" is not very descriptive of what a vignette is and in any case
another step could be eliminated if the vignettes were listed right on the
HTML help page near the top.  These two items would reduce the number
of steps from 5 to 3.

- perhaps help(package = mypackage), which currently lists the DESCRIPTION,
help files and vignettes should allow each of these to be clickable rather than
just read only.

On 5/15/07, Seth Falcon <sfalcon at fhcrc.org> 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.
>
> Cheers,
>
> + seth
>
> --
> Seth Falcon | Computational Biology | Fred Hutchinson Cancer Research Center
> http://bioconductor.org
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>