[Rd] Wishlist: Navigate to "Index" page of help when no topic (PR#13872)

Romain Francois romain.francois at dbmail.com
Wed Aug 5 08:24:13 CEST 2009 

Hello,

I'm jumping a bit late on this, but what about something like:

index?survival

or more generally

foo?bar

with the ability for the user/package to define what the combination 
"foo"/"bar" means. At the moment, the way "package?survival" is handled 
is to :
- create the string "package-survival"
- call help with it

Romain



On 08/05/2009 02:10 AM, murdoch at stats.uwo.ca wrote:
> On 04/08/2009 7:33 PM, Steven McKinney wrote:
>>> -----Original Message-----
>>> From: Duncan Murdoch [mailto:murdoch at stats.uwo.ca]
>>> Sent: Tuesday, August 04, 2009 8:03 AM
>>> To: Steven McKinney
>>> Cc: r-devel at stat.math.ethz.ch; R-bugs at r-project.org
>>> Subject: Re: [Rd] Wishlist: Navigate to "Index" page of help when no
>>> topic specified (PR#13860)
>>>
>>> On 7/28/2009 6:30 PM, smckinney at bccrc.ca wrote:
>>>> Hi all,
>>>>
>>>> When I install a new package, and don't yet know any function names,
>>>> I have to play the "poor man's game" to get to the standard
>>>> help system "Index" page for the package:
>>> You could complain to the package author or maintainer, who should have
>>> created a help alias with the package name so that ?survival would give
>>> you something useful.  But I would guess R 2.10.x or 2.11.x will do
>>> that
>>> automatically.
>>>
>>> Duncan Murdoch
>> Unfortunately it happens frequently - hopefully I
>> don't have to complain so much - I'd rather figure
>> out code to get to the index page!
>>
>> When you say "I would guess R 2.10.x or 2.11.x will do
>> that automatically" do you mean
>> ?survival::
>> or some similar incantation
>> will take me to the Index or 00Index page?
>
> I would guess package?survival will take you to a help page that is
> similar to what you get now in the flat display from
> library(help=survival).  Ideally it will have a link on it to the index
> page.  It is possible that ?survival will work too; that may be more
> controversial, because for many packages (e.g. boot) an alias like that
> is already defined, pointing to something other than the package main page.
>
>> Do I need to propose code or is it already
>> known how to do this within the R core group?
>
> I doubt if code to do that would be accepted (since it will be redundant
> once the above changes are in place), but posting it to r-devel might
> help people in the meantime.  You should look at the tools package,
> which has a number of functions that are used by R for constructing the
> help pages; there's probably something there that will let you construct
> a link to the index fairly easily.
>
> Duncan Murdoch
>
>> Best
>> Steve McKinney
>>
>>
>>>> Poor Man's Game -=20
>>>>    Load new package;=20
>>>>    issue search() command;
>>>>    find position (say N) of loaded package;=20
>>>>    issue objects(pos =3D N) command;
>>>>    get name of a random function (san newFunction);=20
>>>>    issue ?newFunction command;
>>>>    scroll to bottom of page;=20
>>>>    click on the "Index" hyperlink
>>>>
>>>> There are other variations, but they all involve this=20
>>>> long march to the Index page.
>>>>
>>>>
>>>> What I'd like to be able to do is enter the command
>>>>
>>>>> help(package =3D "survival")
>>>> or
>>>>
>>>>> ?survival::
>>>> and get the usual hyperlinked help page displayed (the "00Index"
>>> page)
>>>> instead of the static "text only" display or an error message
>>>>
>>>> (for example, on Windows, this equates to invoking
>>>> "C:/PROGRA~1/R/R-29~1.1/library/survival/chm/00Index"
>>>> on Apple Mac,
>>>>
>>> "/Library/Frameworks/R.framework/Resources/library/survival/html/00Inde
>>> x.ht=
>>>> ml"
>>>> etc.)
>>>>
>>>>
>>>> Details:
>>>> ---------------
>>>>
>>>> The help() function returns an object of
>>>> class "help_files_with_topic".
>>>> The object consists of a character vector
>>>> with several attributes.
>>>>
>>>> PC:  Windows XP
>>>>
>>>>> library("survival")
>>>>> foo<- help("aareg", package =3D "survival")
>>>>> class(foo)
>>>> [1] "help_files_with_topic"
>>>>> foo[1]
>>>> [1] "C:/PROGRA~1/R/R-29~1.1/library/survival/chm/aareg"
>>>>> attributes(foo)
>>>> $call
>>>> help(topic =3D "aareg", package =3D "survival")
>>>>
>>>> $pager
>>>> [1] "internal"
>>>>
>>>> $topic
>>>> [1] "aareg"
>>>>
>>>> $tried_all_packages
>>>> [1] FALSE
>>>>
>>>> $type
>>>> [1] "chm"
>>>>
>>>> $class
>>>> [1] "help_files_with_topic"
>>>>
>>>>> bar<- help("", package =3D "survival")
>>>>> class(bar)
>>>> [1] "help_files_with_topic"
>>>>> bar[1]
>>>> [1] NA
>>>>> attributes(bar)
>>>> $call
>>>> help(topic =3D "", package =3D "survival")
>>>>
>>>> $pager
>>>> [1] "internal"
>>>>
>>>> $topic
>>>> [1] ""
>>>>
>>>> $tried_all_packages
>>>> [1] FALSE
>>>>
>>>> $type
>>>> [1] "chm"
>>>>
>>>> $class
>>>> [1] "help_files_with_topic"
>>>>
>>>> If I alter the character vector to
>>>> point to "00Index"
>>>>
>>>>> bar[1]<- "C:/PROGRA~1/R/R-29~1.1/library/survival/chm/00Index"
>>>>> bar
>>>> I see exactly what I've been attempting to achieve.
>>>>
>>>>
>>>> Mac OS X:
>>>>
>>>>> foo<- help("aareg", package =3D "survival")
>>>>> foo[1]
>>>> [1]
>>> "/Library/Frameworks/R.framework/Resources/library/survival/html/aareg.
>>> =
>>>> html"
>>>>> attributes(foo)
>>>> $call
>>>> help(topic =3D "aareg", package =3D "survival")
>>>>
>>>> $pager
>>>> [1] "/Library/Frameworks/R.framework/Resources/bin/pager"
>>>>
>>>> $topic
>>>> [1] "aareg"
>>>>
>>>> $tried_all_packages
>>>> [1] FALSE
>>>>
>>>> $type
>>>> [1] "html"
>>>>
>>>> $class
>>>> [1] "help_files_with_topic"
>>>>
>>>>> bar<- help("", package =3D "survival")
>>>>> bar[1]
>>>> [1] NA
>>>>> bar[1]<-
>>> "/Library/Frameworks/R.framework/Resources/library/survival/htm=
>>>> l/00Index.html"
>>>>> bar
>>>> Again I see exactly what I've been after.
>>>>
>>>> Running R in Emacs on Mac OS X:
>>>>
>>>>> foo<- help(topic =3D "aareg", package =3D "survival")
>>>>> foo[1]
>>>> [1]
>>> "/Library/Frameworks/R.framework/Resources/library/survival/html/aareg.
>>> =
>>>> html"
>>>>> attributes(foo)
>>>> $call
>>>> help(topic =3D "aareg", package =3D "survival")
>>>>
>>>> $pager
>>>> [1] "/Library/Frameworks/R.framework/Resources/bin/pager"
>>>>
>>>> $topic
>>>> [1] "aareg"
>>>>
>>>> $tried_all_packages
>>>> [1] FALSE
>>>>
>>>> $type
>>>> [1] "html"
>>>>
>>>> $class
>>>> [1] "help_files_with_topic"
>>>>
>>>>> bar<- help(topic =3D "", package =3D "survival")
>>>>> bar[1]
>>>> [1] NA
>>>>> bar[1]<-
>>> "/Library/Frameworks/R.framework/Resources/library/survival/htm=
>>>> l/00Index.html"
>>>>> bar
>>>> Help for '' is shown in browser /usr/bin/open ...
>>>> Use
>>>>          help("", htmlhelp =3D FALSE)
>>>> or
>>>>          options(htmlhelp =3D FALSE)
>>>> to revert.
>>>> Again, what I've been trying to achieve.
>>>>
>>>> When a user loads a new library and doesn't yet know any function
>>> names,
>>>> I think
>>>>> help(package =3D "newLibrary")
>>>> or
>>>>> ?newLibrary::
>>>> should perform the above action whenever possible instead of
>>>> producing static help or an error message.
>>>>
>>>> The "00Index" 'object' should be available for such use
>>>> whenever it exists. =20
>>>>
>>>> I have not yet worked out all the coding details to make this happen,
>>>> but before I do, am I missing some key point?  Any reasons why this
>>>> would be a Bad Idea?
>>>>
>>>>
>>>>
>>>> Steven McKinney, Ph.D.
>>>>
>>>> Statistician
>>>> Molecular Oncology and Breast Cancer Program
>>>> British Columbia Cancer Research Centre
>>>>
>>>> email: smckinney +at+ bccrc +dot+ ca
>>>>
>>>> tel: 604-675-8000 x7561
>>>>
>>>> BCCRC
>>>> Molecular Oncology
>>>> 675 West 10th Ave, Floor 4
>>>> Vancouver B.C.
>>>> V5Z 1L3
>>>> Canada


-- 
Romain Francois
Professional R Enthusiast
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr
|- http://tr.im/vsK1 : R parser package on CRAN
|- http://tr.im/vshK : Transfer files through Rserve
`- http://tr.im/vfxe : R GUI page on the R wiki

More information about the R-devel mailing list