[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 5:06 PM
> 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 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.

Yes, package?survival and help(package = survival) and ?survival
all are currently in use which is why I propose
?survival::
with no topic after the "::" as an incantation to go to the 00Index 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.

Thanks for the information.  I'll review package tools and
work out some demonstrative code.

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