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

[Damian Betebenner]

Philippe,

Thank you. I saw the search that lists the man pages first and then the other finds after.
I really like how nicely the Wiki format makes the Rhelp page look. Color makes things much
easier for the eye. 

I think it's just my preference, but I find it more elegant to have the exact man page come up instead of having to click on the link again. However, if you think that a users clicking on a command will often use the search
results provided, then that's the way to go. 

Another possiblity one might consider with the difficulty level stuff is to do something similar to what
Don Knuth did in the TeX book. When a tricky part in the description comes along, have the author note
it with an indicator (Knuth used a "curve in the road" pictogram). 

Regards,

Damian  


 |  On Mon, 30 Jan 2006 22:56:30 +0100
 |  Philippe Grosjean <phgrosjean at sciviews.org> wrote:
>>>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
>>>> 
>>>> 
>>>

Damian Betebenner
Educational Research, Measurement & Evaluation
Lynch School of Education
Boston College
Chestnut Hill, MA 02467

(617) 552 4491