[R] a proposal regarding documentation

Mon Jun 15 13:17:11 CEST 2009

John Sorkin wrote:
> R 2.8.1, Firefox 3.0.11, windows XP 
> Philippe,
> I suspect there are more substantial problems with the link to the WIKI
> then you thought. When I tried your code I got a page that contained
> nothing more than (excluding the nice graphic header and the index on
> the left-hand page):
> 
>  Trace: » barplot
> == Rwiki file not found! ==
> 
> There is a helpful discussion of adding labels to barplots here:
> https://stat.ethz.ch/pipermail/r-help/2002-October/025879.html  
> 
> 
> This WIKI page is not at all useful,it does not as you suggested it
> does not contain  the help page of ?barplot in wiki format as you
> suggested int would!
> John

Still the problem with the cache. I refreshed the page, and now it 
appears as it should.
Best,

PhG

> 
> John David Sorkin M.D., Ph.D.
> Chief, Biostatistics and Informatics
> University of Maryland School of Medicine Division of Gerontology
> Baltimore VA Medical Center
> 10 North Greene Street
> GRECC (BT/18/GR)
> Baltimore, MD 21201-1524
> (Phone) 410-605-7119
> (Fax) 410-605-7913 (Please call phone number above prior to faxing)
> 
>>>> Philippe Grosjean <phgrosjean at sciviews.org> 6/15/2009 4:42 AM >>>
> Ironically, this function is present since the beginning, although a 
> little buggy. If you try this in R on a computer that is connected to 
> the Internet:
> 
> wikihelp <- function(topic)
>    browseURL(paste("http://wiki.r-project.org/rwiki/rhelp.php?id=",
>      topic, sep = ""))
> wikihelp("barplot")
> 
> You got the help page of ?barplot in wiki format (with a few 
> presentation bugs, but everything is there, basically)... plus a Wiki 
> discussion section where people can add more material, links, etc.
> 
> The help page is not physically contained in the wiki page, but it is a
> 
> file stored elsewhere on the R Wiki server, and that is supposed to be
> 
> updated regularly (but it is not the case for the moment). In the wiki
> 
> page you see, there is only a ~~RDOC~~ marker indicating where to 
> include the help page.
> 
> I have a problem with the R Wiki cache: until someone adds comments to
> 
> such a page, the content is not refreshed, but you just see ~~RDOC~~.
> 
> Try, for instance:
> 
> wikihelp("chisq.test")
> 
> If the engine thinks 'topic' is ambiguous, it displays a list of 
> possibilities (i.e., our wikihelp() function is somehow a mix of help()
> 
> and of apropos()). For instance:
> 
> wikihelp("help")
> 
> 
> This should not be ambiguous, but it is considered as it currently by 
> rhelp.php (a minor bug probably easy to correct).
> 
> Finally, all wiki pages are spelled with lowercase. It is the same for
> 
> help pages. So,
> 
> wikihelp("RSiteSearch")
> wikihelp("rsitesearch")
> 
> lead to the same rdoc:utils:rsitesearch wiki page. I have no solutions
> 
> for that!
> 
> So, to conclude, most of the required mechanism is already installed on
> 
> R Wiki. It  just needs a little bit of debugging and fine-tuning to 
> become completely operational. A little help here would be very
> appreciated!
> 
> ... and, of course, a refined version of the wikihelp() function must
> be 
> made widely available to "reveal" this function. One could even
> consider 
> to write a pager that displays local help page and warns if there are 
> comments on this topic posted on the wiki... or that link to a personal
> 
> wiki engine where everybody could add its own comments to the help 
> pages, with full-text search ability!
> 
> Best,
> 
> Philippe Grosjean
> 
> ..............................................<°}))><........
>   ) ) ) ) )
> ( ( ( ( (    Prof. Philippe Grosjean
>   ) ) ) ) )
> ( ( ( ( (    Numerical Ecology of Aquatic Systems
>   ) ) ) ) )   Mons-Hainaut University, Belgium
> ( ( ( ( (
> ..............................................................
> 
> Gabor Grothendieck wrote:
>> In PHP and also in MySQL the manual has a wiki capability
>> so that users can add notes at the end of each page, e.g.
>>
>> http://www.php.net/manual/en/functions.variable-functions.php 
>>
>> http://dev.mysql.com/doc/refman/4.1/en/update.html 
>>
>> That would combine documentation and wiki into one. Here it would
>> involve copying the R help pages into the wiki in a readonly mode
> with the
>> writeable wiki portion at the end of each such page.  It would also
> be
>> necessary to be able to update the help pages in the wiki when new
> versions
>> became available.
>>
>> No explicit email group or coordination would be needed.  It would
> also address
>> the organization problem as they could be organized as they are now,
> i.e. into
>> packages: base, stats, utils, ...
>>
>> It would require the development of a program to initially copy the
> help pages
>> and to update them while keeping the notes in place whenever a new
> version
>> of R came out.
>>
>> On Sun, Jun 14, 2009 at 5:35 PM, Peter
>> Flom<peterflomconsulting at mindspring.com> wrote:
>>> I certainly don't have anything against the WIKI, but I think that
> the documentation
>>> is where the action is, especially for newbies.  It's the  natural
> first step
>>> when you want to learn about a function or when you  get an error
> message you
>>> don't understand.
>>>
>>> Peter
>>>
>>> Peter L. Flom, PhD
>>> Statistical Consultant
>>> www DOT peterflomconsulting DOT com
>>>
>>> ______________________________________________
>>> 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.
>>>
>>
> 
> Confidentiality Statement:
> This email message, including any attachments, is for th...{{dropped:6}}
> 
> ______________________________________________
> 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.