[R] R help question: How can we enable useRs to contribute corrections to help files faster ?

[Duncan Murdoch]

Gabor Grothendieck wrote:
> On Sun, Feb 28, 2010 at 9:43 AM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
>   
>> On 28/02/2010 9:08 AM, Gabor Grothendieck wrote:
>>     
>>> On Sun, Feb 28, 2010 at 8:59 AM, Duncan Murdoch <murdoch at stats.uwo.ca>
>>> wrote:
>>>       
>>>> On 28/02/2010 7:19 AM, Gabor Grothendieck wrote:
>>>>         
>>>>> The name of the package is at the top of each help page and then
>>>>> library(help = myPackage) would get you the maintainer info.  Or in
>>>>> place of the last step googling for CRAN myPackage would get to a page
>>>>> like this:
>>>>> http://cran.r-project.org/web/packages/zoo/index.html
>>>>> so it could be done in two steps.
>>>>>
>>>>> What would be nice would be if the R help systems HTML help page for
>>>>> each command had a link to a local version of the above page for the
>>>>> associated package (and perhaps the HTML Index page for the package
>>>>> would also link to it).  Then it would just be a matter of bringing up
>>>>> the help page and clicking on the package name at the top.
>>>>>           
>>>> Not all of the information on that page would make sense locally.  Some
>>>> of
>>>> it is there to help you decide whether to download the package, or to
>>>> actually download it.
>>>>
>>>> The things I see that aren't available in the package index page in
>>>> R-devel:
>>>>
>>>>  - CRAN checks
>>>>  - download links
>>>>  - reverse dependencies
>>>>
>>>> Am I missing something?  None of those seem like they'd be sensible
>>>> locally.
>>>>         
>>> By Index page I was referring to the page you get when you click Index
>>> at the bottom of any HTML help file.  After clicking Index you get an
>>> HTML page that gives a clickable list of help pages for that package.
>>> You don`t get the description of the package, the name and contact
>>> info to the maintainer, or a link to such info.  For the
>>> helloJavaWorld package this is what you get (where I have added a star
>>> after each link):
>>>
>>> Hello Java World
>>> Documentation for package ‘helloJavaWorld’ version 0.0-6
>>> User Guides and Package Vignettes
>>>
>>> Read overview* or browse directory*.
>>>
>>> Help Pages
>>>
>>> helloJavaWorld* Function to say hello from a Java class
>>>       
>> That looks like 2.10.x or earlier.  In R-devel (to be 2.11.0) you get:
>>
>> Documentation for package ‘helloJavaWorld’ version 0.0-7
>>
>>    * DESCRIPTION file.
>>    * Overview of user guides and package vignettes; browse directory.
>>
>> Help Pages
>> helloJavaWorld  Function to say hello from a Java class
>>
>> The only addition for that particular package is the link to the DESCRIPTION
>> file, which contains most of the additional information that's on the CRAN
>> page.  Other pages will also show links to demos and package NEWS.
>>
>>     
>
> That's great. Looks like you have already anticipated this.
>
> Would still be nice to have
>
> - a second link to the Index at the top of each help page since its
> typically off the screen otherwise.
>   

Yes, I agree.  In fact, I think the whole system needs to be updated.  
Anyone like doing HTML design?
> - also if the DESCRIPTION could be HTMLized with links that would be
> nice.  The software that puts the DESCRIPTION file info up onto CRAN
> already can do that so the capability seems to exist.
>   

Sure, but remember that CRAN is not part of R, so the code needs to be 
extracted from the CRAN code (which I don't have a copy of), and 
rewritten to suit the new context.  It may not be any easier to do that 
than to redo it from scratch, but in any case, it needs someone to 
volunteer to do it (and I think it should be part of the HTML design 
mentioned above.
> - a link from the Index or possibly right from each help page to the
> help.start() page so that once you are in HTML you can just click
> about rather than having to go back to R and then back into help.
> Its normal in web pages that there is a link on every one of them back
> to the home page.  Typically clicking the site name or logo at the top
> gets you there.
Currently from any help page you can get there in two clicks:  the 
"Index" link at the bottom of the page takes you to the package index, 
the up arrow on the package index takes you to the help.start() page.  
But I agree this could be improved: see above.

Duncan Murdoch