[R] Navigate to Index page of a package from R command prompt

[Steven McKinney]

Okay, I've worked out much of the details on my PC and Mac.

What I'd like to be able to do is enter the command

> help(package = "survival")

or

> ?survival::

and get the usual hyperlinked help page displayed instead
of the static "text only" display or an error message.

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 = "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 = "aareg", package = "survival")

$pager
[1] "internal"

$topic
[1] "aareg"

$tried_all_packages
[1] FALSE

$type
[1] "chm"

$class
[1] "help_files_with_topic"

> bar <- help("", package = "survival")
> class(bar)
[1] "help_files_with_topic"
> bar[1]
[1] NA
> attributes(bar)
$call
help(topic = "", package = "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 = "survival")
> foo[1]
[1] "/Library/Frameworks/R.framework/Resources/library/survival/html/aareg.html"
> attributes(foo)
$call
help(topic = "aareg", package = "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 = "survival")
> bar[1]
[1] NA
> bar[1] <- "/Library/Frameworks/R.framework/Resources/library/survival/html/00Index.html"
> bar

Again I see exactly what I've been after.

Running R in Emacs on Mac OS X:

> foo <- help(topic = "aareg", package = "survival")
> foo[1]
[1] "/Library/Frameworks/R.framework/Resources/library/survival/html/aareg.html"
> attributes(foo)
$call
help(topic = "aareg", package = "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 = "", package = "survival")
> bar[1]
[1] NA
> bar[1] <- "/Library/Frameworks/R.framework/Resources/library/survival/html/00Index.html"
> bar
Help for '' is shown in browser /usr/bin/open ...
Use
	help("", htmlhelp = FALSE)
or
	options(htmlhelp = 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 = "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.  (I've not yet investigated all the
details to answer when it is and is not created in the
Help building exercise of package building.)

I can work out the coding details to make this happen,
but am I missing some key point?  Any reasons why this
would be a Bad Idea?



Best

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







> -----Original Message-----
> From: Gabor Grothendieck [mailto:ggrothendieck at gmail.com]
> Sent: Thursday, July 23, 2009 4:48 PM
> To: Steven McKinney
> Cc: R-help at r-project.org
> Subject: Re: [R] Navigate to Index page of a package from R command
> prompt
> 
> Try
> 
> enter at the R console: help.start()
> and then when the help comes up in your browser click on Packages
> and then click on the package you want
> and then click on the help file you want
> 
> On Thu, Jul 23, 2009 at 3:30 PM, Steven McKinney<smckinney at bccrc.ca>
> wrote:
> >
> > Hi all,
> >
> > Is there a way to navigate directly to the "Index" page of help
> > for a package?
> >
> > Here's my connundrum:
> >
> > I download and install package "foo".
> > I don't know what functions are in package "foo",
> > so I can't invoke the help for package "foo" via
> >> ?someFunction
> >
> > help(package = "foo")
> > pops up some non-hyperlinked information page, not
> > package foo's help Index page.
> >
> > If the package author kindly made a "foo" object or function
> > and put that in package "foo", then
> >> ?foo
> > works and yields a help page for package "foo".
> > Now at the bottom of the help page is a hyperlink "Index"
> > and I can click that to navigate to the main help Index page
> > (the page I really want to get to straight from the R
> > command line).
> >
> > I see that the link to "Index" for package "foo" appears always to be
> > (on my Mac)
> >
> file:///Library/Frameworks/R.framework/Resources/library/foo/html/00Ind
> ex.html
> >
> > e.g.
> >
> file:///Library/Frameworks/R.framework/Resources/library/cmprsk/html/00
> Index.html
> >
> >
> file:///Library/Frameworks/R.framework/Resources/library/utils/html/00I
> ndex.html
> >
> > Is there a command from the R listener that can take me directly to
> > this "00Index.html" page of help for package "foo"?
> >
> > something like
> >> help("00Index", package = "utils")
> >
> > (but this does not work)?
> >
> > Any info appreciated
> >
> > Best
> >
> > Steven McKinney
> >
> > Statistician
> > Molecular Oncology and Breast Cancer Program
> > British Columbia Cancer Research Centre
> >
> > ______________________________________________
> > R-help at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-help
> > PLEASE do read the posting guide http://www.R-project.org/posting-
> guide.html
> > and provide commented, minimal, self-contained, reproducible code.
> >