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

Duncan Murdoch murdoch at stats.uwo.ca
Sun Feb 28 19:38:35 CET 2010 

On 28/02/2010 1:32 PM, Gabor Grothendieck wrote:
> I wonder if this could be made pluggable in the sense that anyone
> could develop a CRAN package that hooks into the help system and takes
> over.  If its already like that perhaps all that is needed is some
> documentation/guidance on how to develop such a package.  There could
> be multiple alternative help packages that hook into the help system
> on CRAN.  That might be the best way to involve the community since it
> involves less coordination to accomplish once the documentation was
> written.

That's a good idea.  The documentation has been published here:

http://journal.r-project.org/archive/2009-2/RJournal_2009-2_Murdoch+Urbanek.pdf

I'd be happy to elaborate on any of the missing bits, or add what's 
missing so that others can do this in a package.

Duncan Murdoch

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

More information about the R-help mailing list