From murdoch at stats.uwo.ca  Wed Apr 30 12:53:07 2008
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Wed, 30 Apr 2008 06:53:07 -0400
Subject: [Rd] RFC: What should ?foo do?
In-Reply-To: <18456.5426.84057.765126@stat.math.ethz.ch>
References: <48110D8B.10300@stats.uwo.ca>
	<48115131.7000402@comcast.net>	<4811B9EC.3010701@stats.uwo.ca>
	<4811F8A8.1050108@comcast.net>	<f8e6ff050804250831g7198fe33s6e92a13ed7deb3ca@mail.gmail.com>	<481202A4.2030508@comcast.net>	<eb555e660804251054kaabb1c4r237007ff5703ca5f@mail.gmail.com>	<alpine.LFD.1.10.0804251931290.23000@gannet.stats.ox.ac.uk>	<48139CC2.8090801@stats.uwo.ca>
	<18456.5426.84057.765126@stat.math.ethz.ch>
Message-ID: <48184F93.5080901@stats.uwo.ca>

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.

Duncan Murdoch



[Rd] RFC: What should ?foo do?
Duncan Murdoch