[R-wiki] Geshi, tool-tips, function-to-url capacity

Philippe Grosjean phgrosjean at sciviews.org
Mon Jan 30 22:56:30 CET 2006


Damian Betebenner wrote:
> All,
> 
> I don't know whether any decision was made on how to attempt to provide links within code to Rhelp.
> One possibility (that I now have working) is to take all the R help files from their directory structure and
> place them in a single directory and use the GeShi function-to-url link:
> 
> http://www.addresshere/Rhelp/{FNAME}.html

There are actually three possibilities already investigated with GeSHi:

1) Something like you propose (was the first trial). This is not that 
simple for the following reasons (at least): (1) help files do not 
always bear the name of the function, several function can share the 
same help file, and methods are handled a little bit differently, (2) 
you can have two different functions with the same name in different 
packages and (3) that directory with everything "flatten" in it will be 
a mess.

2) A Rhelp.php program that dispatch help request to Wiki pages the same 
way as help() does in R, a good idea that does not need to flatten all 
the doc, but...

3) The default search interface of DokuWiki which nicely displays first 
all the pages in all namespaces bearing the name of the function (that 
is, most of the time, the documentation we are looking for!), followed 
by a list of pages with the same "word", ranked by hits.

The conclusion was: why to reinvent the wheel if the search engine is so 
nice (remember that DokuWiki creates an index of all words in all Wiki 
pages for a lightning speed search feature). The only remaining problems 
are:

a) What to do with functions whose man pages do not bear the same name 
as the function. The solution I proposed was to simply generate static 
redirection pages bearing the name of the function.

b) What to do with generic functions/methods? The solution I proposed 
was to create an additional namespace in the doc, called '0__generic__' 
that has one page constructed per generic function (both S3/S4 mixed 
together) and a list of link to pages documenting the generic function, 
the default method and all other methods found during construction of 
the Wiki R documentation pages.

This mechanism is very simple and very efficient. You will notice that 
GeSHi is already configured that way (only documentation pages are 
missing for the moment, except for 'mean' and 'AsIs', ...). What we need 
now, is to rework Rdconv (a Perl script in R) to make it generating 
automatically Wiki pages from .Rd files, and then, to make a batch file 
on the Wiki server that updates regularly Wiki R doc pages according to 
changes on both CRAN and Bioconductor. This was already discussed and it 
is in the TODO list.

> That is, "flatten" the R help files. All that is required for this to work is a good R.php language file 
> combined with a directory containing files for all the commands. Links within the command files also 
> redirect appropriately. I would be willing to volunteer to keep an up-to-date R.php language
> file. 

Would you rather work on Rdconv?

> This seems more in line with what a user would be interested in getting were they to click on a command
> within some code instead of having a search done that results in numerous peripheral results.

No, the search page displays first the pages with the name of the 
function, that is, the corresponding man pages with the system explained 
hereabove. Then, you have a dotted line separating these page from the 
regular search on text inside the other pages. You should regard what 
appears beneath the dotted line as on optional plus.

The problem, for the moment, is that you have nothing on top of the 
dotted line... just because the R help man pages are not converted yet 
into Wiki pages... and what we need here is a good Rdconv-to-wiki.

Please, try clicking on 'mean' to see that mechanism in action, because 
the doc for mean is in the Wiki (note that it is currently in two 
places: in rdoc and in documentation, that is why you got two pages for 
'mean'; this will be fixed as soon as possible).

Best,

Philippe Grosjean


> Regards,
> 
> Damian
> 
> 
> Damian Betebenner
> Educational Research, Measurement & Evaluation
> Lynch School of Education
> Boston College
> Chestnut Hill, MA 02467
> 
> (617) 552 4491
> 
> _______________________________________________
> R-sig-wiki mailing list
> R-sig-wiki at r-project.org
> https://stat.ethz.ch/mailman/listinfo/r-sig-wiki
> 
>



More information about the R-sig-wiki mailing list