[R-SIG-Mac] Cocoa Help System Totally Busted(tm)? And Other Random Notes (Not a Bug Report!)

[Byron Ellis]

Disclaimer: To Simon and Stefano, this does not constitute a bug 
report---I know you guys are busy and have enough on your plate w.r.t. 
R (and doing a great job), let alone your Real Jobs. Its more thinking 
out loud in the (apparently) rapidly growing community of OS X R 
users---it seems like there have been more messages on this list in the 
last two weeks than the last six months, which is great.

Ok, so after a very quick hack to add back and forward buttons and make 
the current toolbar a real toolbar, it appears that the Help system is 
generally broken.

The hack that grabs '?' and 'help' is seems to be the culprit (but I 
see why its there, discussed below)---? is actually both a binary and a 
unary operator so calls of x?y don't get snagged and valid calls to 
help() erroneously bring up the HTML help (help("foo",offline=TRUE), 
for example, does not work anymore). Its fine for casual use, but it 
breaks for heavy users of S4 classes (e.g., Bioconductor users).

Unfortunately, there are a couple of problems that account for the 
hack's existence:
1) R internal help goes through the general pager so, under normal 
circumstances, we end up with non-linkable HTML files. Its possible to 
improve the current pager to support underlines and such, but it seems 
a waste.

2) We can force HTML help (essentially set htmlhelp=TRUE under the Aqua 
platform) and add .show_help_on_topic_as_HTML to the aqua-specific 
subdirectory of package:utils to route to an internal call (say, 
Re_show_help) that brings it up using WebKit (or, if web kit isn't 
available routes to the user's local web browser).

Sadly, this modifies the semantics of help(htmlhelp=TRUE) under OS X, 
which is sort of lame. We could have an option in a preferences panel 
to allow users to route to the default (or an arbitrary) HTML viewer. 
However, its my best proposal at this point (and I've already 
implemented a chunk of it so I can keep going if y'all would like).

Turns out Duncan is right. We really do want ?foo to be an alias for 
show(help("foo")). Especially since it would be much easier to track 
the path through the help system if URLs were of the form 
"help://utils/foo" or something and not "http://...."

More Things Noted:

Only two-level nesting in the Workspace Browser doesn't work:

data(iris)
nested = c()
nested$someting = iris

doesn't let you drill down into "something". I'm guessing that this 
wasn't intentional as editing from the browser != nested$something = 
edit(nested$something)  (presumably the observation below would go 
towards remedying this problem)


Things that would be Fun:

dragging an element from the workspace browser to the console would 
paste it. I.e. dragging "Sepal.Length" from iris would paste 
iris[["Sepal.Length"]]. Even cooler would be cross-app drag-n-drop that 
pastes print(iris) when you drag iris, but thats more time consuming. 
;-) I may take a shot at the former since I think it would be fairly 
easy (though from a quick glance at the code, it probably requires a 
weak reference back link to the parent item in the former case). (My 
thought is not that it would actually be in the console work 
flow---more allowing drop targets in user-supplied things. Like a 
simple regression who's interface was just a plot and dragging 
"Sepal.Width" to the y-axis reruns the regression with "Sepal.Width" as 
the response. You get the idea.)

---
Byron Ellis (ellis at stat.harvard.edu)
"Oook" -- The Librarian