[Rd] RFC: What should ?foo do?

[Duncan Murdoch]

Marc Schwartz wrote:
> Duncan Murdoch wrote:
>   
>> Currently ?foo does help("foo"), which looks for a man page with alias 
>> foo.  If foo happens to be a function call, it will do a bit more, so
>>
>> ?mean(something)
>>
>> will find the mean method for something if mean happens to be an S4 
>> generic.  There are also the type?foo variations, e.g. methods?foo, or 
>> package?foo.
>>
>> I think these are all too limited.
>>
>> The easiest search should be the most permissive.  Users should need to 
>> do extra work to limit their search to man pages, with exact matches, as 
>> ? does.
>>
>> We don't currently have a general purpose search for "foo", or something 
>> like it.  We come close with RSiteSearch, and so possibly ?foo should 
>> mean RSiteSearch("foo"), but
>> there are problems with that: it can't limit itself to the current 
>> version of R, and it doesn't work when you're offline (or when 
>> search.r-project.org is down.)  We also have help.search("foo"), but it 
>> is too limited. I'd like to have a local search that looks through the 
>> man pages, manuals, FAQs, vignettes, DESCRIPTION files, etc., specific 
>> to the current R installation, and I think ? should be attached to that 
>> search.
>>
>> Comments, please.
>>
>> Duncan Murdoch
>>     
>
> Duncan,
>
> I agree in principle with the points that you raise. I suspect that at 
> least in part, it might assist new users with some of the issues that 
> were raised in the latest incarnation of the 'we need better 
> documentation' thread on r-help.
>
> I am not convinced that ?foo should do this however. help("foo") 
> conceptually seems predicated upon the notion that a user is looking for 
> a reference/help page for a specific function or descriptor called 
> 'foo'. The user knows the name of the function or descriptor ...

With the current definition, that's correct, though man("foo") might be 
a better match to Unix-users expectations for a function that did that.  
For a naive user, help("foo") suggests that they're looking for help on 
"foo".
>
> ...  and should 
> not have to wait for a search function to locate it or conceptually 
> related terms.  If the user has a large number of CRAN packages 
> installed, such a search can take a rather long time. That's an issue 
> for example with help.search().
>   

As Brian and Hadley said, that's an implementation issue, already being 
addressed.

> That being said and being a firm believer in incrementalism, perhaps the 
> first step should be to create a new function, called esearch() [as in 
> extended search] or doc.search() [as in documentation search] or even 
> search.all(). This new function would facilitate searching all of the 
> local objects that you list and perhaps others. It would by default be 
> uber-inclusive of all categories of such objects. It would support 
> functionality along the lines of help.search() in allowing for the use 
> of regex and fuzzy matching via grep()/agrep().
>   

Definitely there would need to be a new function, with a new name; if we 
were attaching the name to ? somehow, then it wouldn't matter much what 
name was used.

I haven't done it, but I suspect we could introduce special behaviour 
for ??foo very easily.  We could even have a whole hierarchy:

?foo, ??foo, ???foo, ????foo, ...

> The downside of this approach is that we would add yet another search 
> function to the list of those already available, each of which searches 
> a focused subset of the potential targets for assistance, whether local 
> or online. Thus, it would require some level of understanding of the 
> general structure of the myriad of local and online resources of R 
> related assistance.
>   

Part of the idea behind my suggestion is that it should be somewhat 
automatic for a new user to learn about the different types of help.  
One way for this to happen is the current one:  expect them to find and 
read the manuals.  The suggestion is to make it easier to find the 
different types.  The risk of this is that exposing a new user to a wide 
range of different kinds of results would just be confusing.

> Perhaps ?help could be augmented a bit in elucidating some of these 
> issues. The See Also there does not reference apropos() for example and 
> it might be worthwhile adding something along the lines of the bullets 
> in the "Do your homework before posting" section in the Posting Guide. 
> Thus ?help can become something of a "first place to look - local 
> centralized help resource" for users to identify the tiered help 
> resources that are available and to also provide a framework for how to 
> use those resources. One could also have links to the online pages for R 
> News, R Books, the R Wiki, the R Graph Gallery, Contributed 
> Documentation, Bioconductor and Other Documentation, so that users 
> become more aware of help resources beyond the documentation installed 
> with R by default.
>   

Those are probably good ideas, but my guess would be that few users read 
?help. 

> A longer term plan could be to look to consolidate some of these 
> functions into a single help/search function perhaps circa R version 
> 3.0.0. That would enable some time for thoughtful consideration and 
> feedback.
>   

As all the recent bug reports show, we don't really get feedback until 
code is released, so there's not much of an advantage of 3.0.0 (unless 
we really break the current system) over 2.8.0. 

Duncan Murdoch

> That's my US\$ $\displaystyle e^{i\pi} + \sum_{n=1}^\infty \frac{1}{2^n} 
> + 2(10^{-2})$
>
> :-)
>
> HTH,
>
> Marc
>