not sure how long ago i made some of these changes... the sleep

[ess.git] / doc / README.SPLUS4WIN

-*- text -*-

ESS: Using S-Plus 4.x for Windows
=================================

(also see detailed help at the end, for more information)

Beginning with ESS 5.1.2 we are able to use inferior iESS mode to
communicate directly with a running S-Plus 4.x process using the
Microsoft DDE protocol.  We use the familiar (from Unix ESS) C-c C-n
and related key sequences to send lines from the S-mode file to the
inferior S process.  We continue to edit S input files in ESS[S] mode
and transcripts of previous S sessions in ESS Transcript mode.  All
three modes know the S language, syntax, and indentation patterns and
provide the syntactic highlighting that eases the programming tasks.

ESS (originally S-mode) was initially designed for use with S and
S-PLUS(tm) on the Unix computers with interprocess communication using
the Unix standard input and standard output protocols.  S-Plus 4.x was
designed for the Microsoft Windows 95/98/NT and uses DDE as the
interprocess communications protocol.  The protocols are very
different.

See the document README.S for detailed information on:
- general Emacs features.
- Editing files.
- using transcripts.
- Philosophies
- Scenarios for use (possibilities, based on actual usage)

The following are not identical in MS Windows to the similarly named
sections in README.S and are covered in this document:
- running an S process as an inferior process to Emacs
- ESS-help: assistance with viewing help


INSTALLATION
============

The easiest way to install ESS on Windows machines is to place the
unzipped directory tree on the machine in, for specificity,
  c:/emacs/ess-5.1.21/
Then add the following line to your ~/_emacs (or ~/.emacs) file:
  (load-file "c:/emacs/ess-5.1.21/lisp/ess-site.el")

For improved startup efficiency (but not execution efficiency) you can
follow the more elaborate installation procedures described in
README.S.  These procedures depend on your already having installed
/bin/sh and make, programs that come with the Unix-like utilities from
Cygwin:
   http://sourceware.cygnus.com/cygwin/


iESS: Inferior ESS processes
============================

iESS (inferior ESS) is the mode for interfacing with active
statistical processes (programs).  This mode behaves very differently
with S-Plus 4.x for Windows than it does for the Unix versions of
S-Plus.

S-Plus 4.x for Windows is full-featured Windows program.  It has GUI
subwindows, icons, menus, buttons, and Windows-style interprocess
communication.  By contrast Unix versions of S-Plus have only the
equivalent of the Commands window (running in an ordinary xterm (or
other shell window)) and the Graphics windows.

iESS for S-Plus 4.x is completely compatible with all the Windows
features.  At this time it has been used extensively with NTemacs 20.3.l
  http://www.cs.washington.edu/homes/voelker/ntemacs.html
  http://www.cs.washington.edu/homes/voelker/ntemacs/ftp/
iESS uses the ddeclient program included as part of the NTemacs distribution.
We recommend that the user install bash as the shell under emacs.
  http://sourceware.cygnus.com/cygwin/
Our programs do work should the user choose to use one of the Windows
shells (command.com on 95/98, or cmd.exe on NT).

The starting key sequence depends on the shell the user prefers:

 bash users: The S-Plus user starts S-Plus from within emacs with
   "M-x S" (or with "M-x S+4").

 msdos users: The S-Plus user starts S-Plus from within emacs with
   "M-x S+4-msdos".  msdos users MUST remember to close S-Plus cleanly
   and then close the *S+4 ddeclient* buffer with `exit', or take the
   risk of not being able to shut down the computer cleanly.

Either of these emacs command sequences starts the usual S-Plus 4.x
window.  There may be a slight delay before the emacs window can be
used.  The S-Plus window must have a visible Commands window placed on
the left side of the S-Plus window.  We recommend placing the S-Plus
window on the left side of the screen and the emacs window on the
right side of the screen.  This placement permits activity in the
S-Plus commands window to be monitored while lines are sent over from
the active emacs window.

The user then sends individual lines or groups of lines to the S-Plus
process using the emacs command C-c C-n (for lines), C-c C-r (for
regions), C-c C-b (for the entire buffer).  The lines magically appear
in the S-Plus Commands window, as if they had been typed manually or
been sent by mouse copy and paste commands.  The results of the
commands appear in the S-Plus Commands window.  No results come back
to the emacs process (this is the major difference between the Unix
and Windows actions of ESS).

An entire file can be sent over with C-c C-l.  In this case, only the
command `source("filename")' appears in the S-Plus Commands window.
No input statements or output from the commands appear.  All global
assignments have been made.

In order to create an S transcript it is necessary to

(1) highlight a region in the S-Plus Commands window (the easiest way
    is to use the Ctrl+A keystroke or the "Edit/Select All" menu
    command) and then copy Ctrl+C it.  Ctrl+C is a standard Windows
    keystroke.

(2) open an ESS Transcript file, for example myfile.st, in emacs.  The
    suffix ".st" stands for S Transcript.  When a myfile.st file is
    created or read it always comes in as a read-only file.  This is a
    protection to keep the user from accidentally changing an
    historical file.  Make it writable with C-x C-q and the paste the
    copied region using C-y (the standard emacs yank command (which
    corresponds to the Windows paste)).

Caution: switching from the emacs window to the S-Plus window causes
finger confusion as the keystroke commands are not the same.

Once the transcript has been created in an emacs buffer it has most of
the standard iESS (inferior ESS) mode features, including sending
lines back to the active statistical process (program).  This features
include:

- proper indenting, generated by both [Tab] and [Return].
- color and font highlighting based on syntax.
- ability to resubmit the contents of a multi-line command
  to the executing process with a single keystroke [RET].
- transcript recording and editing


Optional Ways to Start S-Plus 4.x with emacs
============================================

1. If you already have an S-Plus 4.x window and wish to add emacs
   access to that window, then you can start an emacs iESS buffer with
   "M-x S+4-existing" (bash users) or "M-x S+4-msdos-existing" (msdos users).

2. If you really like the S-Plus to run inside an emacs *S+4* buffer,
   just the way it does in Unix, then you can start an emacs iESS
   buffer with "M-x Sqpe+4".  There is no interactive graphics
   available in this arrangement.  Postscript graphics to a file are
   available.  None of the GUI menus and buttons are available.


ESS-help: assistance with viewing help
======================================

The key sequence C-c C-v entered from any ESS buffer sends a help
request to the running S-Plus.  Help files in S-Plus 4.x for StatSci
distributed functions use the Windows Help mechanism.  They do not
appear in emacs buffers.


Recommended Settings on first use of a new _Data directory
==========================================================

The first time you use S-Plus in a new directory you must do some setup.

- Click Window/Commands Window

- Click Options/General Settings/Startup.
  Click Select Data Dialog off.
  Click Command Line on.
  Click Object Browser on.

Assuming you have downloaded and are using the gnuserv/gnuclient
programs:
    http://www.cs.washington.edu/homes/voelker/ntemacs/contrib/gnuserv.zip
- Click Options/General.Settings/Computations.
  Change Editor to gnuclient.
  Change Pager to gnuclientw.
Note these are different.  The behavioral difference is that gnuclient
will freeze S-Plus until "C-x #" is typed to the emacs buffer.
This is the correct behavior when you are using the S function edit().
With emacs as your editor, you are less likely to need the edit() function.

- Click Options/Command Line Options/Options/Key Scroll/Page Keys.

- Click Options/Graph Options/Options/Auto Pages/Every Graph.

- Click Options/"Save Window Size/Properties as Default"


History of M-x S+4 and related functions
========================================

In May 1998, Brian Ripley wrote an early version of an interface
between ESS and S-Plus using the DDE concept.  The original version
demonstrated feasability of the concept.  It was limited to a single
line (that is, C-c C-n worked correctly when the S statement was
complete on a single line).  The region and buffer commands C-c C-r
and C-c C-b did not work.

In December 1998, Richard Heiberger completely rewrote the DDE
interaction to use the ddeclient program that was first distributed
with NTemacs 20.3.1.  He further developed the remaining functions
to the point where all ESS functions now work with S-Plus 4.x on the
Windows operating systems.


Detailed Help For S-PLUS 2000 and the License Manager
(Thanks to David Brahm, <brahm@alum.mit.edu>)
=====================================================

Found the solution to getting Sqpe-mode to work with the license manager - I
set S_ELMHOST in Emacs with (setenv "S_ELMHOST" "123.45.67.890"), instead of
trying to make it a command-line argument.  Thus I was also able to reduce
the number of modifications to "essd-sp4.el".  I still change the delay time
by hand (from 30 seconds to 10); I wish this were a variable so I could just
put (setq-default inferior-ess-delay 10) in my .emacs.

I've attached my new installation instructions, with these modifications.

-- David Brahm

How to Install S-Plus, Emacs, ESS, and Cygwin on NT. (David Brahm 11/9/99)

1) S-Plus:
>From MathSoft <http://www.mathsoft.com/splus> (800)569-0123
Desktop icon "C:\Program Files\sp2000\cmd\splus.exe" u:/splus/init.s
                s_proj=p:/home/s  s_elmhost=123.45.67.890
              Start in P:\Home\S
U:/Splus/init.s contains:
  library("Lib", first=T, lib.loc="u:\\Splus")
U:/Splus/Lib contains directories: _Data, _Prefs, Flat, and Source
Resize S-Plus window to match Emacs window.
In Options > General > Startup, check "Command Line"
   Options > "Save Window Size/Properties as Default"

2) Emacs:
<ftp://ftp.gnu.org/gnu/windows/emacs/latest>             get "em2041.zip"
<http://www.gnu.org/software/emacs/windows/ntemacs.html> for FAQ
Extract (with WinZip) to C:\, thus creating C:/emacs-20.4
Double-click on C:/emacs-20.4/bin/addpm.exe, copy icon to desktop.
In "Emacs" icon shortcut, change to Start in P:/Home
Create file C:/emacs-20.4/site-lisp/site-start.el (see below).
User can put additional customization in P:/Home/.emacs

3) ESS:
<http://ess.stat.wisc.edu/>  get "ess-5.1.21.zip"
Extract to C:\emacs-20.4, thus creating C:/emacs-20.4/ess-5.1.21
In C:/emacs-20.4/ess-5.1.21/lisp/essd-sp4.el:
  Change (sleep-for 30) to (sleep-for 10)  (twice)

4) Cygwin:
<http://sourceware.cygnus.com/cygwin/>  get "full.exe" (or "usertools.exe")
Double-click on full.exe and accept all defaults, installing to C:/Cygnus
Make directories C:/bin and C:/tmp
Copy C:/Cygnus/Cygwin-B20/H-i586-cygwin32/bin/sh.exe to C:/bin
Right-click My Computer > Properties > Environment, and append this to Path:
    ";c:\bin;c:\Cygnus\Cygwin-B20\H-i586-cygwin32\bin"
  *or* put this line into C:/autoexec.bat:
    set PATH=c:\bin;c:\Cygnus\Cygwin-B20\H-i586-cygwin32\bin
W95/98 only: If an error "Out of environment space" occurs, add to
config.sys:
  shell=C:\command.com /e:4096 /p


Here is my site-start.el file:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
(setenv "HOME" "P:/Home")
(setenv "PATH"
        "C:/Cygnus/Cygwin-b20/H-i586-cygwin32/bin;C:/Progra~1/sp2000/cmd")

; ESS and customization:
(load "C:/Emacs-20.4/ess-5.1.21/lisp/ess-site")
(setenv "SHELL" "C:/Cygnus/Cygwin-b20/H-i586-cygwin32/bin/bash")
(setenv "S_ELMHOST" "123.45.67.890")
(setenv "S_FIRST" "source(\"U:/Splus/init.s\")")     ; Initialization file
(setenv "SHOME" "C:/Progra~1/sp2000")
(setq-default inferior-Sqpe+4-program-name "c:/Progra~1/sp2000/cmd/Sqpe")
(setq ess-ask-for-ess-directory nil)
(setq ess-directory "P:/Home/S/")
(setq ess-execute-in-process-buffer t)
(make-local-variable 'comment-indent-function)
(setq-default comment-indent-function 'ess-comment-indent)
(fset 'run-s "\C-x2\M-xS\C-m")
(global-set-key "\M-s" 'run-s)         ; ESC-s runs "run-s" which starts S

; Window size:
(set-frame-size (selected-frame) 80 56)

; Always auto-fill:
(setq-default auto-fill-function 'do-auto-fill)
(setq-default fill-column 79)

; Macros and set-keys:
(global-set-key "\C-u" 'query-replace-regexp)
(load "hscroll")
(defun flat (tabw) "Turns off line-wrap; prefix sets tab width."
  (interactive "p")
  (turn-on-hscroll) ; (setq truncate-lines 1)
  (if (> tabw 1) (setq tab-width tabw))
  (redraw-display))
(global-set-key "\C-c\C-f" 'flat)

; Fonts (uncomment the next line for a bolder font):
; (set-default-font "-adobe-courier-bold-r-normal--*-140-*-*-m-*-iso8859-1")
(global-font-lock-mode t)
(custom-set-variables)
(custom-set-faces
 '(font-lock-comment-face
   ((((class color) (background light)) (:foreground "Firebrick"))))
 '(font-lock-string-face
   ((((class color) (background light)) (:foreground "SeaGreen"))))
 '(font-lock-keyword-face
   ((((class color) (background light)) (:foreground "MediumBlue"))))
 '(font-lock-constant-face
   ((((class color) (background light)) (:foreground "VioletRed"))))
 '(font-lock-type-face
   ((((class color) (background light)) (:foreground "Goldenrod"))))
 '(font-lock-variable-name-face
   ((((class color) (background light)) (:foreground "Blue"))))
 '(font-lock-function-name-face
   ((((class color) (background light)) (:foreground "VioletRed"))))
)