;;; Documentation for ess-r-gui.el --- Support for running Rgui on
;;; Windows as an inferior Emacs process

;; Copyright (C) 2008 A.J. Rossini, Richard M. Heiberger, Martin
;;	Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.

;; Original Author:  Richard M. Heiberger <rmh@temple.edu>
;; Created: 10 Mar 2008
;; Maintainers: ESS-core <ESS-core@stat.math.ethz.ch>

This is preliminary documentation for the preliminary release of M-x
Rgui, a new ESS function that allows access to the Rgui Console on
Windows from an emacs R-mode buffer.

Here are the steps.

1. Update your R package 'tcltk2' to 1.0-6 or newer
   {E.g. inside R: install.packages("tcltk2") # or
                    update.packages(check.built=TRUE) }

2. Start Rgui from an icon and enter these three lines into the R Console
     library(tcltk2)  ## >= 1.0-6
     .ess.command <- function() source("c:/temp/ess-tempfile.R", echo=TRUE)
     tclFun(.ess.command)

3. Set the environment variable R_HOME in emacs, for example with
     (setenv "R_HOME" "c:/progra~1/R/R-2.6.1")

4. Make sure you have a directory named c:/TEMP

5. Then, load ess-r-gui.el into emacs and type
     M-x Rgui

This will create a new MSDOS command buffer named "*R*" which will
allow communication with the Rgui Console.  Most ESS keys work.

I have tested these

C-c C-n works for complete commands.  multi-line commands will get
        a syntax error.

C-c C-c works for lines surrounded by a blank line at top and bottom.

C-c C-r works for a highlighted region.

C-c C-v works for help



The technology is similar (not identical) to the technology I used in
connecting to the S-Plus Gui on Windows.  In Rgui I send the
higlighted lines to a file and then use the execdde.exe from tcltk2 to
source() the lines.

The source() function suppresses intermediate blank lines and trailing
comments.  When the seven lines below are sourced, only lines
1,2,4,5,6 are echoed.  Lines 3 and 7 are not echoed.  This means that
well-commented user source code will not have complete comments in the
output transcript in the Console.

## comment 1
123

## comment 4

456
## comment 7


Possible improvements

1. Duncan suggested I write my own ess.source to echo all lines.  That
is another project for another day.

2. Currently M-x Rgui connects to an existing Rgui that has loaded the
tcltk2 package.  It should be easy to detect whether such a process is
running and start one if not.

3. I would like single line of a multi-line command to be sent over
with a series of C-c C-n, as works for other R and S-Plus interfaces.
It can't be done as long as the R source() command is used.