RFC: What should ?foo do?
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