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

[Duncan Murdoch]

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 
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.

> 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.

Duncan Murdoch