[R] a proposal regarding documentation

[baptiste auguie]

I knew I had seen this in action! But as you mention, most pages only 
display ~~RDOC~~ at the moment.
I second the idea of using the wiki for such collaborative work. If the 
current (r-devel) version of all help pages could be automatically 
copied to the wiki, users would have a convenient way to propose 
changes. The coloured diff, user identification, and RSS feed make for a 
very user-friendly alternative to svn access (unthinkable anyway for 
non-R core members).

Best,

baptiste


Philippe Grosjean wrote:
> 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
> ( ( ( ( (
> ..............................................................


-- 
_____________________________

Baptiste Auguié

School of Physics
University of Exeter
Stocker Road,
Exeter, Devon,
EX4 4QL, UK

Phone: +44 1392 264187

http://newton.ex.ac.uk/research/emag