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

Gabor Grothendieck ggrothendieck at gmail.com
Sun Feb 28 19:32:38 CET 2010 

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.

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