[R] a proposal regarding documentation

[John Sorkin]

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


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}}