[R] Improving help in R
Duncan Murdoch
murdoch.duncan at gmail.com
Thu Mar 15 12:47:36 CET 2012
On 12-03-14 6:39 PM, Tomáš Křehlík wrote:
> Hello R people
>
> I always wander what other people say about the R help. Finally after some years of using, I decided that it is probably time to try to do something about it, because the feeling of gritting teeth does not go away with years of usage. :) Moreover, I think it is one of the few things where R does not kick asses to the other statistical softwares. So, to the point:
>
> I get the feeling (by some experience with learning programming languages when I am not primarily a programmer but economist/statistician) that structure of help really helps and I would like to have it to go in the way
>
> basic syntax (by basic I really mean only the necessary arguments)
> example for "dummies", to see what it does
> click-here-if-you-want-to-know-more menu/button
> The best documentation that I ever used is probably one of Mathematica, look for example here http://reference.wolfram.com/mathematica/ref/Fit.html (it is somehow related to the stuff below).
>
> So what I did is that I took R help file for Fitting Linear Models ( http://stat.ethz.ch/R-manual/R-patched/library/stats/html/lm.html ) and put it into some more readable shape for me. So I built some other version (actually two) look at http://pinda.sifruje.cz/ . The "original" is just the same text taken and only some basic stuff solved (on my 27 inch monitor, if I make the browser full screen the original help is almost unreadable, because it stretches from one end to the other. Next we already have some pretty good fonts so why not to use them, here Linux Biolinum, and I did some to me aesthetic changes...). The "custom" goes a bit deeper and tries to implement a bit more of my thoughts. The buttons are really made quickly and only as an example. Also I do not claim that the code is anywhere good, I spent like hour or two just sawing some pieces that already lay around web. Just take it as some demonstration.
>
> What I would like to receive from you is your opinions about this topic. The stuff that I did is pretty easy to do even algorithmically (some parser could probably parse the existing help files). The only added value here is making important stuff more visible. I also added the "dummies" example.
>
> So please tell me what you think. I am a bit busy and if I do anything with it I would like to have it thought through carefully beforehand. Also if anybody would be interested in helping, or if he is running similar project, tell me.
One difficulty in getting the help pages to look beautiful is that the
original input is so inconsistent, and package authors (naturally) get
upset when CRAN starts rejecting packages because of errors that used to
be ignored. The current output is definitely a compromise aimed at
making most packages work.
However, this doesn't stop us from using a different style sheet. It
would be very easy to have the system generate pages with markup that
allowed a user to customize fonts, colours, etc. The main difficulty
here is that R users use lots of different systems and lots of different
browsers, so it takes some work to find displays that work everywhere.
(For example, someone mentioned drop caps in your display, but I don't
see those in Firefox on Windows -- presumably I don't have the font you
specified.)
BTW, when you say "some parser could probably parse the existing help
files", it sounds as though you are unaware of the fact that the help
source is in Rd format, and it is parsed into various output formats.
You can see the parser in tools::parse_Rd, and the formatter in
tools::Rd2HTML.
If you want to continue to work on this, I'd be happy to continue the
discussion on R-devel.
Duncan Murdoch
More information about the R-help
mailing list