[R] a proposal regarding documentation

John Sorkin jsorkin at grecc.umaryland.edu
Mon Jun 15 15:55:29 CEST 2009 

Below I have pasted an example from the R WIKI  (which is a copy of a
man page), that illustrates a typical problem with the help system. A
naive reader who wants to know something about the tcltk package will
know little more after reading the page than before he, or she, looked
at the page. Questions that might arise in the mind of the reader would
include, what is the package used for, is it important for me to know
about tcltk if I am to use R, is there an example of the use of tcltk
that I can see, do I need tcltk to use R, what is the DISPLAY variable,
etc. Further explanation in the WIKI would help, but so would a more
comprehensive man page. I don't mean to impugn the people who gave their
time to develop the tcltk-package, its man page or the WIKI; their work
is greatly appreciated. I simply took the man page as an example of
documentation that may not be as well done is the code written to
perform the functions described by the man page. As a long time software
engineer, I know from personal experience that documentation is often
not given as much attention as it deserves.   

MATERIAL BELOW IS TAKEN FROM THE WIKI:

tcltk-package (tcltk)

Tcl/Tk Interface

Description

Interface and language bindings to Tcl/Tk GUI elements.
Details

This package provides access to the platform-independent Tcl scripting
language and Tk GUI elements. See TkWidgets for a list of supported
widgets, TkWidgetcmds for commands to work with them, and references in
those files for more.

The Tcl/Tk documentation is in the system man pages.

For a complete list of functions, use ls(“package:tcltk”).

Note that Tk will not be initialized if there is no DISPLAY variable
set, but Tcl can still be used. This is most useful to allow the loading
of a package which depends on [rp>TclTk] in a session that does not
actually use it (e.g. during installation).


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 7:36 AM >>>
Sorry, after a second request, I got the ==Rwiki file not found!== 
again. Obviously, I have to solve this bug first!

PhG

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

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

More information about the R-help mailing list