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

From: hadley wickham <h.wickham_at_gmail.com>
Date: Fri, 18 May 2007 21:54:58 +0200

> On 5/18/2007 11:11 AM, hadley wickham wrote:
> > On 5/18/07, Duncan Murdoch <murdoch_at_stats.uwo.ca> wrote:
> >> I think we've agreed about adding an option to the vignette() function
> >> to allow the user to choose to see all vignettes in installed packages,
> >> or only those that are attached. Adding this is pretty trivial, and
> >> I'll put it into R-devel soon.
> >>
> >> I'd like to set the default to show only attached packages, which would
> >> be consistent with the behaviour of demo() and data(). Vignettes are
> >> still less common than demos or data, so if I do this, I'll also change
> >> the "none found" message to something like
> >>
> >> > vignette()
> >> no vignettes found
> >>
> >> Use 'vignette(all = TRUE)'
> >> to list the vignettes in all *available* packages.
> >
> > What will happen if you do vignette("svmdoc") when you haven't already
> > loaded the e1071 package? Will the vignette continue to load (useful)
> > or return an error message (consistent with help, and data, I think)?
>
> Currently if you don't say which package to look in, then vignette()
> uses the .packages() function to find a list to search through. I was
> planning to just pass the "all" arg to .packages() as all.available, so
> if all=FALSE (the default I suggested) this case will give the warning
> message
>
> > vignette("svmdoc")
> Warning message:
> vignette 'svmdoc' *not* found
>
> consistent with help(), data(), and demo(). I think this behaviour
> makes sense for those because there may well be duplicates of the same
> name in multiple packages, and you'd usually want to see the attached
> version, rather than some other installed one. This is currently not

Yes, that's reasonable, although I always trip myself up after looking at help(package=XXX) by then trying to look at the individual help files without first loading the package

> much of a problem for vignettes because they are relatively rare and
> collisions don't happen much, but it would be nice if that changed.

Except for my packages where I've named all my introductory vignettes "introduction"! But yes, not a big problem in general.

> > Should data and demo also gain "all" arguments to be consistent?
>
> Probably, and probably other inconsistencies should be fixed too: e.g.
> if there are name collisions, help() offers a list of choices, but
> data() and vignette() just pick the first. (I didn't check demo()).
>
> However, I don't have time to fix all the inconsistencies now, so I
> think I'll set the default to vignette(all=TRUE) (i.e. no change from
> current behaviour), and maybe worry later in the summer about some of
> these other issues.

I think it is a nice change, but anything that can improve the consistency of R functions really makes it easier to learn the language. One could almost imagine making vignette, data and demo more generic in the sense that they each list, and load, some supplementary object provided by a package. I don't think there is anything else of a similar form, though.

Hadley



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Fri 18 May 2007 - 19:58:54 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Fri 18 May 2007 - 20:35:35 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.