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