[Rd] RFC: What should ?foo do?

[Marc Schwartz]

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

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

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.

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.

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.

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

:-)

HTH,

Marc