-*- text -*- ESS: Using S-Plus 4.x for Windows ================================= 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.2/ Then add the following line to your ~/_emacs (or ~/.emacs) file: (load-file "c:/emacs/ess-5.1.2/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.