RFC: What should ?foo do?

On 30/04/2008 2:44 AM, Martin Maechler wrote:

"DM" == Duncan Murdoch <murdoch at stats.uwo.ca>
    on Sat, 26 Apr 2008 17:21:06 -0400 writes:

    DM> On 25/04/2008 2:47 PM, Prof Brian Ripley wrote:

    >> On Fri, 25 Apr 2008, Deepayan Sarkar wrote:

    >>     >>> For what it's worth, I use ?foo mostly to look up usage of 

functions

    >>> that I know I want to use, and find it perfect for that (one 

benefit

    >>> over help() is that completion works for ?). The only thing I miss 

is

    >>> the ability to do the equivalent of help("foo", package = "bar");
    >>> ?bar::foo gives the help page for "::". Perhaps that would be
    >>> something to consider for addition.

    >>     >> That fits most naturally with the (somewhat technical) idea 

that bar::foo     >> becomes a symbol and not a function call.  I believe 
that several of think     >> that is in principle a better idea, but no one 
has as yet (AFAIK) explored     >> the ramifications.

    >>     >> However, 5 mins looking at the sources suggests that it is 

easy to do.


    DM> And you already did.  Thanks!
indeed.

    DM> I'm going to make the following change soon (in R-devel).

    DM> ??foo

    DM> will now be like help.search("foo").  This will work with your 
change,     DM> so ??utils::foo will limit the search to the utils package. 
This is     DM> also quite easy.  A more difficult thing I'd like to do is 
to broaden     DM> the search to look outside the man pages, but that's a 
lot harder, and I     DM> haven't started on it.

    DM> I will also follow Hadley's suggestion and change the format of the 
DM> help.search results, so you can just cut and paste after a question 
mark     DM> to look up the particular topic, e.g.  ??foo gives

    DM> utils::citEntry         Writing Package CITATION Files

    DM> Type '?PKG::FOO' to inspect entry 'PKG::FOO TITLE'.

    DM> I haven't touched the case of ?foo failing; I'll want to try it for 
a     DM> while to decide whether I like it best as is:

    >> ?foo

    DM> No documentation for 'foo' in specified packages and libraries:
    DM> you could try '??foo'

    DM> or whether it should just automatically call help.search, or 
something     DM> in between.

Please the former, at least by default!
[The case of 1500 installed packages was mentioned before...]

Note one thing that hasn't been mentioned before:

help() has had the optional argument
       ' try.all.packages = getOption("help.try.all.packages") '
for many years now, and I have been involved in its history as
well but don't recall all details. IIRC,
help() {and hence "?"} used to *default* to  'try.all.packages = TRUE' for 
a while and later it was the
default for me (and our whole statistics departmental unit).
But we found that it *was* inconvenient that a big search was
started, often just because of a typo.
So I think   ?<non-existing>  should ``answer quickly'' by
default.

Have you tried help.search() lately?  It is now very fast.  I haven't checked 
if help() makes use of the same search mechanism, but presumably it could do 
so, if speed is an issue.

So I would say the speed is a solvable or solved problem.

system.time(help("linear", try.all.packages = TRUE))

system.time(help.search("linear"))

system.time(help.search("linear"))

system.time(help.search("linear"))