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

Wed Aug 5 02:05:46 CEST 2009

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
>>>
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>