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

Sun Feb 28 19:24:10 CET 2010

On 28/02/2010 1:04 PM, Tal Galili wrote:
> Duncan,
> As much as I agree with your remark in the general case, in this case - the
> annoyance is mostly for the next user and not the current one.
> 
> If I spot a typo, after I figure what it had meant - my annoyance is over.
>  I don't have any personal motivation to share the knowledge, asides from my
> good intentions.
> 
> It would seem to me that making my life easier in reporting the error -
> would only do good to the general community.

I agree, and I welcome your contribution.  Take a snapshot of the 
package index page, the DESCRIPTION page, and one or two topic pages 
from the current R-devel.  Redesign them, put them online, respond to 
comments until everyone is convinced (or at least I am) that they can't 
be substantially improved.  If you convince me of that, I'll put them 
(or some approximation to them) into the sources.

> 
> I think the idea of adding a second link to the Index at the top of every
> help, is easy to do and would benefit the community member who wishes to
> contact the author.

That's not enough.  It will take about the same amount of work on my end 
to do *each* small change or a single big change, so I'm not going to do 
a sequence of incremental changes.

> 
> I also think that adding the e-mail of the maintainer might even be better
> (since I remember that when I started using R, I didn't even know I had
> someone to contact regarding problems with it).

It is already there.

Duncan Murdoch

> This is the place people turn to for help, it makes sense (at least in my
> humble opinion) to help the users find other help from that location. (the
> same way we provide "see also" and other useful links)
> 
> 
> Tal
> 
> 
> 
> 
> ----------------Contact
> Details:-------------------------------------------------------
> Contact me: Tal.Galili at gmail.com |  972-52-7275845
> Read me: www.talgalili.com (Hebrew) | www.biostatistics.co.il (Hebrew) |
> www.r-statistics.com (English)
> ----------------------------------------------------------------------------------------------
> 
> 
> 
> 
> On Sun, Feb 28, 2010 at 7:24 PM, Duncan Murdoch <murdoch at stats.uwo.ca>wrote:
> 
>> On 28/02/2010 12:04 PM, Gabor Grothendieck wrote:
>>
>>> 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.
>>>
>> That's one argument.  Another is that the more of an annoyance it is, the
>> more likely someone will be motivated to fix it.  If we do a partial job to
>> remove the annoyance, the long term improvement might never happen.
>>
>> Duncan Murdoch
>>
>>
>> ______________________________________________
>> R-help at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-help
>> PLEASE do read the posting guide
>> http://www.R-project.org/posting-guide.html
>> and provide commented, minimal, self-contained, reproducible code.
>>
>