[R] Improving help in R

[Barry Rowlingson]

2012/3/14 Tomáš Křehlík <tomas.krehlik at gmail.com>:
> Hello R people

> 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)

type 'args(lm)'

> example for "dummies", to see what it does

type 'example(lm)', or 'example(lm,give.lines=TRUE)' if you want to
see the example and not run it.

> click-here-if-you-want-to-know-more menu/button

 type '?lm'

 I don't think I've ever used the html help system in R, except to go
'ooh, there's an HTML help system'.

> 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.

I jush had a look at a couple of html help pages for the first time in
ages, and yes they could possibly benefit from some restyling, but you
have to remember that these are generated from text .Rd files, and
also need to be able to be rendered into plain text for us ESS-using
dinosaurs. I think I would first rewrite the Rd to HTML converter to
make the HTML more semantic, then use CSS to style it better - perhaps
the various sections could go into tabs or an accordion-style UI
component.

Of course the real way to do this is to do some user experience
research. I mostly use the help to remember argument names and
ordering, which I can actually do by typing foo( and hitting TAB
(twice in the command line).

But certainly the lines are waaay too long on a decent sized monitor.
Which is why an 80-column ESS window is winning! :)

Barry