[ESS] ess-help+.el

[Vitalie Spinu]

Dear ESS users and developers,

I've been working for a while on improving ess-help and you can find
the result here: http://vsmisc.googlecode.com/svn/trunk/ess-help+.el

Diff is here
http://code.google.com/p/vsmisc/source/diff?spec=svn18&old=11&r=19&format=side&path=%2Ftrunk%2Fess-help%2B.el
but you better use ediff.

Most important changes:

1) new function ess-completion-read: it uses IDO interface for
completion whenever available and falls back on completing-read
otherwise.  Set 'ess-use-ido-p' to nil if you don't want ido
altogether.

2) new function 'ess-display-index' (bound to "i" in ess-help-map). It
displays nicely linked index file put automatically in ess-help-mode
with all the usual shortcuts available; p and n have modified
behavior.

3) new function 'ess-display-vignettes' (bound to v in ess-help-mode)
to display linked vignette file. Links will open rnw or R files
directly in emacs, p and n have modified behavior.

4) new function 'ess-display-help-in-browser' opens current page in
html browser.  Bound to "w" in ess-help-mode-map.

5) bonus function 'ess-install.packages' (bound to C-c i), it
retrieves all available R packages and asks you through IDO interface
which to install.  So for example to install ggplot2 you need to type
C-c i gg RET.

**internals notes**
6) new internal function ess--switch-to-help-buffer which takes care
of how ess-help buffer is displayed. It was extracted from
ess-display-help-on-object and is now used by other help functions as
well.


7) All new functions (index, vignettes, browser) are designed to be
easily expendable to other dialects. Each function starts with a (cond
((string-match "^R" ess-dialect) ...)) statement which initializes all
necessary regexps and command to be used latter. To extend to other
languages one has to add corresponding customization in cond
statement. Presumably for S+, a very small modification of R
initialization is necessary. Can anyone look into it?

8) removed curr-* kludge in ess-display-help-on-object, it was not
   necessary.

**breaking changes**
9) ess-display-help-on-object uses C-u argument to both, update the
cache of help objects and refetch help. Before, there was no easy way
to update the cached list of objects.

   Original behavior of C-u was to re-fetch the help page. How useful
   is this feature? Is anyone using it? Is there a problem if updating
   and re-fetching live on the same C-u or I should put re-fetching on
   C-u C-u?

10) "q" is bound to bury-buffer instead of ess-switch-to-end-of-ESS in
ess-help-mode-map.

    The original behavior is inconsistent with the behavior of help
and info files in emacs, and ess-switch-to-end-of-ESS is also bound to
C-c C-z which is default for ess-mode buffers. Bury-buffer in my view
is much better and healthier default. In case of piling of help
buffers (which often happens by pressing "h" (help) and now by
"i"(index) and "v" (vignettes)), "q" just buries the buffer and
reveals the preceding one, just as-if going backwards in history.


I really hope this will end up in ESS. For time being people can
download the file and put

(setq ess-help-mode-map nil) (load "~/path/to/ess-help+.el")

in their emacs after (load "ess-site.el").

There are a few other places in ess where ess-completion-read might be
used instead of the competing-read - R-site-search, ess-switch-process
etc.

I tested it with emacs and xemacs as much as I could and must admin
making stuff work in xemacs is much harder:(. Is there still someone
out there using Xemacs?

In Xemacs some features are not fully supported. First, in the index
listing there are no links and you will have to load the package
before being able to navigate to the help page (in emacs the function
associated with the link takes care of loading the package).  Second,
'ess-display-vignettes' in xemacs does call browseVignettes to display
it in browser instead of displaying it directly in ess-help buffer. I
just could not make the regexp work in xemacs (regexp-bulder appears
to be broken xemacs).



Waiting for your feedback,
Vitalie.