Re: [Rd] RFC: What should ?foo do?
On Wed, 30 Apr 2008, Duncan Murdoch wrote: On 30/04/2008 2:44 AM, Martin Maechler wrote: "DM" == Duncan Murdoch <[EMAIL PROTECTED]> 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 ? 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. There are some possible improvements as yet. Hadley mentioned keeping binary indices -- we do per-package and could per-library. Just opening 1700 files can be quite slow on some systems -- this is one of the areas where you see the benefits of Unix-alike file systems. A lot of the speed ups are generic, e.g. internal file.path. I get system.time(help("linear", try.all.packages = TRUE)) user system elapsed 10.948 2.620 37.808 system.time(help.search("linear")) user system elapsed 8.219 0.432 28.358 so there is room for improvement in help(). However, the re-run system.time(help.search("linear")) user system elapsed 1.951 0.003 1.960 shows the benefits of caching. (This is on a not particularly fast machine with all of CRAN and BioC installed, in UTF-8: and I know of some ways to improve performance in UTF-8.) It's all a question of resources and who is prepared to contribute. I sped help.search() up ca 3x because 100s was too slow for me -- 30s the first time in a session is OK. (And incidentally disc caching means that the next session got system.time(help.search("linear")) user system elapsed 7.180 0.246 7.627 , so the main issue is disc access.) -- Brian D. Ripley, [EMAIL PROTECTED] Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/ University of Oxford, Tel: +44 1865 272861 (self) 1 South Parks Road, +44 1865 272866 (PA) Oxford OX1 3TG, UKFax: +44 1865 272595 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
On 30/04/2008 2:44 AM, Martin Maechler wrote: "DM" == Duncan Murdoch <[EMAIL PROTECTED]> 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 ? 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 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> "DM" == Duncan Murdoch <[EMAIL PROTECTED]> > 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 ? should ``answer quickly'' by default. Martin Maechler DM> Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
Peter Dalgaard wrote: > Duncan Murdoch wrote: > >> 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, ... >> >> >> > Heh, that's rather nice, actually. In words, that could read > > ?foo: tell me about foo! > ??foo: what can you tell me about foo? > ???foo: what can you tell me about things like foo? > foo: I don't know what I'm looking for but it might be something > related foo? > I quite like this. It seems very intuitive to me -- just match the number of question marks to the level of my frustration. Pat > You do have to be careful about messing with ?, though. I think many > people, including me, would pretty quickly go nuts if ?par suddenly > didn't work the way we're used to. > > __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
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. And you already did. Thanks! I'm going to make the following change soon (in R-devel). ??foo will now be like help.search("foo"). This will work with your change, so ??utils::foo will limit the search to the utils package. This is also quite easy. A more difficult thing I'd like to do is to broaden the search to look outside the man pages, but that's a lot harder, and I haven't started on it. I will also follow Hadley's suggestion and change the format of the help.search results, so you can just cut and paste after a question mark to look up the particular topic, e.g. ??foo gives utils::citEntry Writing Package CITATION Files Type '?PKG::FOO' to inspect entry 'PKG::FOO TITLE'. I haven't touched the case of ?foo failing; I'll want to try it for a while to decide whether I like it best as is: > ?foo No documentation for 'foo' in specified packages and libraries: you could try '??foo' or whether it should just automatically call help.search, or something in between. Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
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. -- Brian D. Ripley, [EMAIL PROTECTED] Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/ University of Oxford, Tel: +44 1865 272861 (self) 1 South Parks Road, +44 1865 272866 (PA) Oxford OX1 3TG, UKFax: +44 1865 272595 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
Dear all, Why not leave ? more-or-less as it is (at least for ?foo) and add arguments to help() for other kinds of searches? Perhaps the kind of search that help() does by default could be set as an option. Regards, John -- John Fox, Professor Department of Sociology McMaster University Hamilton, Ontario, Canada web: socserv.mcmaster.ca/jfox > -Original Message- > From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] > project.org] On Behalf Of Deepayan Sarkar > Sent: April-25-08 1:54 PM > To: R-devel > Subject: Re: [Rd] RFC: What should ?foo do? > > 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. > > -Deepayan > > __ > R-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
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. -Deepayan __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
hadley wickham wrote: >> It seems logical to me that such a resource be embedded up front in "Intro" >> with it also being included within the existing help system and referenced >> in the start up banner message. > > That would help if anyone actually read the startup banner. The next > time you're in front of an audience of people who have been using R > for a couple of weeks, ask them how to cite R. > > Hadley That might be supportive of having the startup banner be nothing more than a version/copyright notice and then leave you at a '>" prompt. I am open to the notion however, that some do read it, perhaps less so over time as they just want to get to the prompt and effectively become oblivious to the banner. Of course, it ('citation()') is also referenced in the main R FAQ... Marc __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
Duncan Murdoch wrote: > On 4/25/2008 10:16 AM, Robert Gentleman 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. >> >>While I like the idea, I don't really agree with the sentiment >> above. I think that the easiest search should be the one that you want >> the result of most often. >> And at least for me that is the man page for the function, so I can >> check some detail; and it works pretty well. I use site searches much >> less frequently and would be happy to type more for them. > > That's true. > > What's your feeling about what should happen when ?foo fails? present of list of man pages with spellings close to foo (we have the tools to do this in many places right now, and it would be a great help, IMHO, as spellings and capitalization behavior varies both between and within individuals), so the user can select one > > >> >>> >>> 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. >> >> I think that would be very useful (although there will be some >> decisions on which tool to use to achieve this). But, it will also be >> problematic, as one will get tons of hits for some things, and then >> selecting the one you really want will be a pain. >> >> I would rather see that be one of the dyadic forms, say >> >>site?foo >> >> or >>all?foo >> >> one could even imagine refining that for different subsets of the >> docs you have mentioned; >> >>help?foo #only man pages >>guides?foo #the manuals, R Extensions etc >> >> and so on. >> >>You did not, make a suggestion as to how we would get the >> equivalent of ?foo now, if a decision to move were taken. > > I didn't say, but I would assume there would be a way to do it, and it > shouldn't be hard to invoke. Maybe help?foo as you suggested, or man?foo. If not then I would be strongly opposed -- I really think we want to make the most common thing the easiest to do. And if we really think that might be different for different people, then disambiguate the "short-cut", ? in this case, from the command so that users have some freedom to customize, would be my favored alternative. I also wonder if one could not also provide some mechanism to provide distinct information on what is local vs what is on the internet. Something that would make tools like spotlight much more valuable, IMHO, is to tell me what I have on my computer, and what I can get, if I want to; at least as some form of option. Robert > > Duncan Murdoch > -- Robert Gentleman, PhD Program in Computational Biology Division of Public Health Sciences Fred Hutchinson Cancer Research Center 1100 Fairview Ave. N, M2-B876 PO Box 19024 Seattle, Washington 98109-1024 206-667-7700 [EMAIL PROTECTED] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> It seems logical to me that such a resource be embedded up front in "Intro" > with it also being included within the existing help system and referenced > in the start up banner message. That would help if anyone actually read the startup banner. The next time you're in front of an audience of people who have been using R for a couple of weeks, ask them how to cite R. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
Duncan Murdoch wrote: > 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". I agree that man("foo") would be consistent with looking for help with a known specific function. I also agree that Linux/Unix users would expect such behavior. However, I am not sure that Windows users would be so inclined. Certainly as a former Windows user and despite many years of programming experience in various environments, I would not, out of the gate, have instinctively known or thought about man("foo"). That is not to argue against moving in that direction however. In fact, as part of any future consolidation of the myriad help and search functions, it would make a great deal of sense that ?foo become an alias for man("foo") rather than help("foo"). Thus, the other help/search related functions could also consolidate around a mechanism with two key distinctions, that being local versus online sources. >> ... 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. My comment there was more of an observation rather than a criticism and my apologies if it was taken as the latter. I think it is reasonable to expect, that if a useR has 1,300+ CRAN packages installed, that it is going to take longer to search that infrastructure, than if the useR only has a few. I would want to have a reasonable expectation however, that if I used ?t.test as opposed to help.search("t test"), the result would be forthcoming in a more efficient manner in the former case than in the latter. In the former case, I am typically looking for a specific function in a package that is in the search path. In the latter, I am searching for related terms/concepts in all installed packages, etc. >> 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, ... Conceptuall
Re: [Rd] RFC: What should ?foo do?
On 4/25/2008 10:41 AM, Simon Urbanek wrote: > On Apr 25, 2008, at 8:46 AM, Peter Dalgaard wrote: > >> Duncan Murdoch wrote: >>> 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, ... >>> >>> >> Heh, that's rather nice, actually. In words, that could read >> >> ?foo: tell me about foo! >> ??foo: what can you tell me about foo? >> ???foo: what can you tell me about things like foo? >> foo: I don't know what I'm looking for but it might be something >> related foo? >> >> You do have to be careful about messing with ?, though. I think many >> people, including me, would pretty quickly go nuts if ?par suddenly >> didn't work the way we're used to. >> > > I strongly agree with that. > > One potential way out could be to offer some extended fall-back in > case the man page doesn't exist. (I'm not sure I like that, either, > but I could get used to it ;).) > > I don't really have a problem with status quo and I think if you want > proper advanced searches, you should be using (or implementing them) > in the GUIs anyway. That is what the new users will be using (and > looking for) in the first place. If they have to count the question > marks instead, they won't know about it (although I like the idea for > advanced users). I'd like to try to have the search common across all platforms, but the GUIs could present it and the results in their own way. Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> Consistent with this idea would be something like the "I feel lucky" search > on Google, i.e. ?foo would go immediately to the best match, while ??foo > would present a list of possible matches. This is not consistent with > current behaviour, where ?foo will present a list if it matches two or more > topics, but I think we can always rank one ahead of the other based on their > ordering in the search list. I don't know if it will be so easy to rank > hits coming from help.search(), or from other searches that don't exist yet: > but maybe it doesn't matter. If someone doesn't like what they get from > ?foo, they can always try ??foo. That seems like a good compromise to me - it's a metaphor familiar to most people, and corresponds roughly to the current behaviour of help and help.search. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
On 4/25/2008 10:18 AM, hadley wickham wrote: > On Fri, Apr 25, 2008 at 7:46 AM, Peter Dalgaard > <[EMAIL PROTECTED]> wrote: >> Duncan Murdoch wrote: >> > 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, ... >> > >> > >> Heh, that's rather nice, actually. In words, that could read >> >> ?foo: tell me about foo! >> ??foo: what can you tell me about foo? >> ???foo: what can you tell me about things like foo? >> foo: I don't know what I'm looking for but it might be something >> related foo? > > I like the idea, but why do not it automatically and then display the > results on a single page? (i.e. list results in order of specificity) One reason not to do that is that in single-threaded R you are pretty much stuck until it is done. Presumably the more specific search is quicker than the less specific one. And even if we could act on results as soon as they were available, I think a lot of users would wait for the search to stop, so there'd be a perception that it was too slow. One possible change to ?foo that would not be so painful for old-time users would be to try it under its current meaning first, and only fall back to a more general search if that fails. Consistent with this idea would be something like the "I feel lucky" search on Google, i.e. ?foo would go immediately to the best match, while ??foo would present a list of possible matches. This is not consistent with current behaviour, where ?foo will present a list if it matches two or more topics, but I think we can always rank one ahead of the other based on their ordering in the search list. I don't know if it will be so easy to rank hits coming from help.search(), or from other searches that don't exist yet: but maybe it doesn't matter. If someone doesn't like what they get from ?foo, they can always try ??foo. Duncan __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
On 4/25/2008 10:16 AM, Robert Gentleman 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. > >While I like the idea, I don't really agree with the sentiment above. > I think that the easiest search should be the one that you want the > result of most often. > And at least for me that is the man page for the function, so I can > check some detail; and it works pretty well. I use site searches much > less frequently and would be happy to type more for them. That's true. What's your feeling about what should happen when ?foo fails? > >> >> 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. > > I think that would be very useful (although there will be some > decisions on which tool to use to achieve this). But, it will also be > problematic, as one will get tons of hits for some things, and then > selecting the one you really want will be a pain. > > I would rather see that be one of the dyadic forms, say > >site?foo > > or >all?foo > > one could even imagine refining that for different subsets of the docs > you have mentioned; > >help?foo #only man pages >guides?foo #the manuals, R Extensions etc > > and so on. > >You did not, make a suggestion as to how we would get the equivalent > of ?foo now, if a decision to move were taken. I didn't say, but I would assume there would be a way to do it, and it shouldn't be hard to invoke. Maybe help?foo as you suggested, or man?foo. Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
On Apr 25, 2008, at 8:46 AM, Peter Dalgaard wrote: > Duncan Murdoch wrote: >> 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, ... >> >> > Heh, that's rather nice, actually. In words, that could read > > ?foo: tell me about foo! > ??foo: what can you tell me about foo? > ???foo: what can you tell me about things like foo? > foo: I don't know what I'm looking for but it might be something > related foo? > > You do have to be careful about messing with ?, though. I think many > people, including me, would pretty quickly go nuts if ?par suddenly > didn't work the way we're used to. > I strongly agree with that. One potential way out could be to offer some extended fall-back in case the man page doesn't exist. (I'm not sure I like that, either, but I could get used to it ;).) I don't really have a problem with status quo and I think if you want proper advanced searches, you should be using (or implementing them) in the GUIs anyway. That is what the new users will be using (and looking for) in the first place. If they have to count the question marks instead, they won't know about it (although I like the idea for advanced users). Cheers, Simon > __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> I would rather see that be one of the dyadic forms, say > >site?foo > > or >all?foo I'd be interested to know how many R users are aware of the dyadic form - I suspect it's very very few. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
On Fri, Apr 25, 2008 at 7:46 AM, Peter Dalgaard <[EMAIL PROTECTED]> wrote: > Duncan Murdoch wrote: > > 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, ... > > > > > Heh, that's rather nice, actually. In words, that could read > > ?foo: tell me about foo! > ??foo: what can you tell me about foo? > ???foo: what can you tell me about things like foo? > foo: I don't know what I'm looking for but it might be something > related foo? I like the idea, but why do not it automatically and then display the results on a single page? (i.e. list results in order of specificity) Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> > But that's just a problem with the current implementation. Better > > indexing could make full text search of all documentation practical > > instantaneous. This is one argument for a centralised documentation > > web site - such indices are much easier to set up in a modern web > > development environment. I could imagine this being an eventual > > feature of crantastic.org, but it requires on some tool to turn Rd > > files into a form more easily parsed with off-the-shelf tools (ideally > > xml). > > > > The search is a lot faster in 2.7.x, but is limited by disc speed (and > hence is relatively slow on Windows -- and I have a box which has both Linux > and Windows on, so I've tested this on identical hardware). R is a dynamic > environment which can change libraries (and their order), add or remove > packages The text search is pretty close to instantaneous (try it a > second time) -- the time is taken building the database for the first use. Would it be possible to build per package help databases during the install (or build?) process? That way all that work could be shifted to one a one off compilation. > Yes, we could do this differently, but some credit for the work already > done would be an encouragement to continue to improve. Sorry! Writing a good text search engine is hard and I didn't mean to disparage the existing work of R-core. The current system works great for the majority of uses. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] 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. While I like the idea, I don't really agree with the sentiment above. I think that the easiest search should be the one that you want the result of most often. And at least for me that is the man page for the function, so I can check some detail; and it works pretty well. I use site searches much less frequently and would be happy to type more for them. > > 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. I think that would be very useful (although there will be some decisions on which tool to use to achieve this). But, it will also be problematic, as one will get tons of hits for some things, and then selecting the one you really want will be a pain. I would rather see that be one of the dyadic forms, say site?foo or all?foo one could even imagine refining that for different subsets of the docs you have mentioned; help?foo #only man pages guides?foo #the manuals, R Extensions etc and so on. You did not, make a suggestion as to how we would get the equivalent of ?foo now, if a decision to move were taken. > > Comments, please. > > Duncan Murdoch > > __ > R-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > -- Robert Gentleman, PhD Program in Computational Biology Division of Public Health Sciences Fred Hutchinson Cancer Research Center 1100 Fairview Ave. N, M2-B876 PO Box 19024 Seattle, Washington 98109-1024 206-667-7700 [EMAIL PROTECTED] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
Duncan Murdoch wrote: > 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, ... > > Heh, that's rather nice, actually. In words, that could read ?foo: tell me about foo! ??foo: what can you tell me about foo? ???foo: what can you tell me about things like foo? foo: I don't know what I'm looking for but it might be something related foo? You do have to be careful about messing with ?, though. I think many people, including me, would pretty quickly go nuts if ?par suddenly didn't work the way we're used to. -- O__ Peter Dalgaard Ă˜ster Farimagsgade 5, Entr.B c/ /'_ --- Dept. of Biostatistics PO Box 2099, 1014 Cph. K (*) \(*) -- University of Copenhagen Denmark Ph: (+45) 35327918 ~~ - ([EMAIL PROTECTED]) FAX: (+45) 35327907 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] 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
Re: [Rd] RFC: What should ?foo do?
On Thu, 24 Apr 2008, hadley wickham wrote: >> 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 > > Is that true? That does limit the usefulness of ? as it implies that > you must already know the function that you need. > >> 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(). > > But that's just a problem with the current implementation. Better > indexing could make full text search of all documentation practical > instantaneous. This is one argument for a centralised documentation > web site - such indices are much easier to set up in a modern web > development environment. I could imagine this being an eventual > feature of crantastic.org, but it requires on some tool to turn Rd > files into a form more easily parsed with off-the-shelf tools (ideally > xml). The search is a lot faster in 2.7.x, but is limited by disc speed (and hence is relatively slow on Windows -- and I have a box which has both Linux and Windows on, so I've tested this on identical hardware). R is a dynamic environment which can change libraries (and their order), add or remove packages The text search is pretty close to instantaneous (try it a second time) -- the time is taken building the database for the first use. Yes, we could do this differently, but some credit for the work already done would be an encouragement to continue to improve. -- Brian D. Ripley, [EMAIL PROTECTED] Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/ University of Oxford, Tel: +44 1865 272861 (self) 1 South Parks Road, +44 1865 272866 (PA) Oxford OX1 3TG, UKFax: +44 1865 272595 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] RFC: What should ?foo do?
> 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 Is that true? That does limit the usefulness of ? as it implies that you must already know the function that you need. > 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(). But that's just a problem with the current implementation. Better indexing could make full text search of all documentation practical instantaneous. This is one argument for a centralised documentation web site - such indices are much easier to set up in a modern web development environment. I could imagine this being an eventual feature of crantastic.org, but it requires on some tool to turn Rd files into a form more easily parsed with off-the-shelf tools (ideally xml). Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] 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 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel