[R-wiki] Geshi, tool-tips, function-to-url capacity
phgrosjean at sciviews.org
Mon Jan 30 22:56:30 CET 2006
Damian Betebenner wrote:
> 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:
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
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
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
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).
> 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
More information about the R-sig-wiki