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 <phgrosj...@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 <phgrosj...@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<peterflomconsult...@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@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@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@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@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@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.
