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

[Steven McKinney]

> -----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?

Do I need to propose code or is it already
known how to do this within the R core group?

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