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

[Gabor Grothendieck]

On Sun, Feb 28, 2010 at 11:52 AM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> 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
>

Couldn't this be separated into short term and long term.  Surely its
trivial to add a second link to the Index at the top of every help
page and that  is the most important of all the wish list items.  That
shouldn't have to wait for a redesign (which could take some time)
since its such an annoyance.