R devel - Jul 2009 - Wishlist: Navigate to "Index" page of help when no topic specified (PR#13860)

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:
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.html"
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/html/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/html/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

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