From h.wickham at gmail.com  Fri May 18 21:54:58 2007
From: h.wickham at gmail.com (hadley wickham)
Date: Fri, 18 May 2007 21:54:58 +0200
Subject: [Rd] RFC: allow packages to advertise vignettes on Windows
In-Reply-To: <464DD3E3.1060908@stats.uwo.ca>
References: <m21whj2e0c.fsf@ziti.local> <464DBA70.7020407@stats.uwo.ca>
	<f8e6ff050705180811g5c19a93fv9afe9e9bc2979db0@mail.gmail.com>
	<464DD3E3.1060908@stats.uwo.ca>
Message-ID: <f8e6ff050705181254w1c79abf1xcf07b89aa6658f6d@mail.gmail.com>

> 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



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