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

[murdoch at stats.uwo.ca]

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

> 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/00Index.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