[ESS] ess-help+.el

[Martin Maechler]

>>>>> Vitalie Spinu <spinuvit.list at gmail.com>
>>>>>     on Sat, 5 Nov 2011 14:33:27 +0100 writes:

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

Very cool!   ... though it takes a *long* time initially for me,
as it indexes all the 2000 packages (or so) I have installed.

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

very nice, though untested!

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

good idea

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

sounds very reasonable... at least if just reading the
description :-)

    > I really hope this will end up in ESS. 

me too... there's another more private e-mail being sent to you,
for that..

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

    > ______________________________________________
    > ESS-help at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/ess-help