4 The ESS Developers proudly announce the release of ESS
8 Emacs Speaks Statistics (ESS) provides an intelligent, consistent
9 interface between the user and the software. ESS interfaces with
10 S-PLUS, R, SAS, BUGS and other statistical analysis packages under the
11 Unix, Microsoft Windows, and Apple Mac OS operating systems. ESS is a
12 package for the GNU Emacs and XEmacs text editors whose features ESS
13 uses to streamline the creation and use of statistical software. ESS
14 knows the syntax and grammar of statistical analysis packages and
15 provides consistent display and editing features based on that
16 knowledge. ESS assists in interactive and batch execution of
17 statements written in these statistical analysis languages.
19 ESS is freely available under the GNU General Public License (GPL).
20 Please read the file COPYING which comes with the distribution, for
21 more information about the license. For more detailed information,
22 please read the README files that come with ESS.
24 1.1 Getting the Latest Version
25 ==============================
27 The latest released version of ESS is always available on the web at:
28 ESS web page (http://ess.r-project.org) or StatLib
29 (http://lib.stat.cmu.edu/general/ESS/)
31 The latest development version of ESS is available via
32 `https://svn.R-project.org/ESS/', the ESS Subversion repository. If
33 you have a Subversion client (see `http://subversion.tigris.org/'), you
34 can download the sources using:
35 % svn checkout https://svn.r-project.org/ESS/trunk PATH
36 which will put the ESS files into directory PATH. Later, within
37 that directory, `svn update' will bring that directory up to date.
38 Windows-based tools such as TortoiseSVN are also available for
39 downloading the files. Alternatively, you can browse the sources with a
40 web browser at: ESS SVN site (https://svn.r-project.org/ESS/trunk).
41 However, please use a subversion client instead to minimize the load
44 If you remove other versions of ESS from your emacs load-path, you
45 can then use the development version by adding the following to .emacs:
47 (load "/path/to/ess-svn/lisp/ess-site.el")
49 Note that https is required, and that the SSL certificate for the
50 Subversion server of the R project is
52 Certificate information:
53 - Hostname: svn.r-project.org
54 - Valid: from Jul 16 08:10:01 2004 GMT until Jul 14 08:10:01 2014 GMT
55 - Issuer: Department of Mathematics, ETH Zurich, Zurich, Switzerland, CH
56 - Fingerprint: c9:5d:eb:f9:f2:56:d1:04:ba:44:61:f8:64:6b:d9:33:3f:93:6e:ad
58 (currently, there is no "trusted certificate"). You can accept this
59 certificate permanently and will not be asked about it anymore.
64 * Languages Supported:
65 * S family (S 3/4, S-PLUS 3.x/4.x/5.x/6.x/7.x, and R)
73 * XLispStat including Arc and ViSta
75 * Editing source code (S family, SAS, BUGS, XLispStat)
76 * Syntactic indentation and highlighting of source code
78 * Partial evaluation of code
80 * Loading and error-checking of code
82 * Source code revision maintenance
84 * Batch execution (SAS, BUGS)
86 * Use of imenu to provide links to appropriate functions
88 * Interacting with the process (S family, SAS, XLispStat)
89 * Command-line editing
91 * Searchable Command history
93 * Command-line completion of S family object names and file
96 * Quick access to object lists and search lists
98 * Transcript recording
100 * Interface to the help system
102 * Transcript manipulation (S family, XLispStat)
103 * Recording and saving transcript files
105 * Manipulating and editing saved transcripts
107 * Re-evaluating commands from transcript files
109 * Help File Editing (R)
110 * Syntactic indentation and highlighting of source code.
112 * Sending Examples to running ESS process.
119 ESS has been tested with
121 * S-PLUS 3.3-4, 4.5, 2000, 5.0-1, 6.0-2, 7.0
135 on the following platforms
139 * Solaris/SunOS (all)
141 * Microsoft Windows 95/98/NT/2000/XP (SPLUS 4.5/2000/6.*, R, SAS and
144 * Apple Mac OS (SAS for OS 9 and R for OS X)
146 with the following versions of emacs
148 * GNU Emacs 20.3-7, 21.1, 21.3, 21.4
150 * XEmacs 21.0, 21.1.13-14, 21.4.0-8, 21.4.9-13(1), 21.4.14-15,
153 ---------- Footnotes ----------
155 (1) require the files.el patch to revert-buffer for the Local
156 Variables updating problem
161 Versions 5.2.x are meant to be release-quality versions. While some
162 new features are being introduced, we are cleaning up and improving the
163 interface. We know about some remaining documentation inconsistencies.
164 Patches or suggested fixes with bug reports are much appreciated!
169 There is a mailing list for discussions and announcements relating to
170 ESS. Join the list by sending an e-mail with "subscribe ess-help" (or
171 "help") in the body to <ess-help-request@stat.math.ethz.ch>;
172 contributions to the list may be mailed to
173 <ess-help@stat.math.ethz.ch>. Rest assured, this is a fairly
174 low-volume mailing list.
176 The purposes of the mailing list include
178 * helping users of ESS to get along with it.
180 * discussing aspects of using ESS on Emacs and XEmacs.
182 * suggestions for improvements.
184 * announcements of new releases of ESS.
186 * posting small patches to ESS.
191 Please send bug reports, suggestions etc. to
193 <ESS-bugs@stat.math.ethz.ch>
195 The easiest way to do this is within Emacs by typing
197 `M-x ess-submit-bug-report'
199 This also gives the maintainers valuable information about your
200 installation which may help us to identify or even fix the bug.
202 If Emacs reports an error, backtraces can help us debug the problem.
203 Type "M-x set-variable RET debug-on-error RET t RET". Then run the
204 command that causes the error and you should see a *Backtrace* buffer
205 containing debug information; send us that buffer.
207 Note that comments, suggestions, words of praise and large cash
208 donations are also more than welcome.
213 * A.J. Rossini (mailto:blindglobe@gmail.com)
215 * Richard M. Heiberger (mailto:rmh@temple.edu)
217 * Kurt Hornik (mailto:Kurt.Hornik@R-project.org)
219 * Martin Maechler (mailto:maechler@stat.math.ethz.ch)
221 * Rodney A. Sparapani (mailto:rsparapa@mcw.edu)
223 * Stephen Eglen (mailto:stephen@gnu.org)
228 ESS is free software; you can redistribute it and/or modify it under
229 the terms of the GNU General Public License as published by the Free
230 Software Foundation; either version 2, or (at your option) any later
233 ESS is distributed in the hope that it will be useful, but WITHOUT
234 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
235 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
236 in the file COPYING in the same directory as this file for more details.
241 Changes/New Features in 5.2.8:
242 * iESS: [Tab] completes *file* names "inside string" as in earlier
243 (<= 5.2.3) ESS versions.
245 Changes/New Features in 5.2.7:
246 * If you use Custom to change the variable ess-toolbar-items, the
247 new toolbar is used in all subsequent ESS buffers.
249 * ESS[SAS]: new feature: if ess-sas-log-max >0 and your .log grows
250 to more than ess-sas-log-max bytes, just the first ess-sas-log-max
251 bytes are refreshed; this is helpful when your .sas program
252 generates lots of error messages and gets too big for emacs to
255 * ESS[R/S]: `M-;' in R/S editing modes will now indent with either
256 one or two hashes depending on context.
258 * ESS[R]: David Whiting's Sweave extensions (to 'noweb') are now
259 available (from ess-swv.el loaded by default).
261 Changes/New Features in 5.2.6:
262 * Removed non-ASCII characters in a few files.
264 * ESS[R]: now works better when UTF-8 locale is active; in
265 particular, you get correct directional quotes in R's startup
266 message for R-devel (unstable development version of R 2.1.0)
267 when using environment variables LANGUAGE=en@quot
270 * ESS[SAS]: toggling of .log mode improved (`F10'); toggling of .lst
271 mode now also available (`C-F10'); killing all buffers associated
272 with .sas program no longer bound to `C-F10' since its a bit
273 overzealous; EXPERIMENTAL new feature: if your .log grows to more
274 than 2.5MB, just the first 2.5MB are refreshed; this is helpful
275 when your .sas program generates lots of error messages and gets
276 too big for emacs to display; the truncation size is controlled by
277 the variable ess-sas-log-max and defaults to 2500000.
279 * S-Plus 7 for Windows is now recognized.
281 * ESS[S] (incl. R): in auto-fill mode, strings are not wrapped
284 * ESS[S] (incl. R): font-lock now correctly differs between R and S,
285 e.g., for "_"; both now fontify warning(.) and S does terminate()
288 * Support for `bell' aka `beep' aka `ding' aka `alarm' in all
289 inferior modes: When \a is output "to the the console" at the
290 beginning of a line, the bell is rung.
292 Changes/New Features in 5.2.5:
293 * ESS[R]: `C-c C-q' or `Quit S' from the menu now should work (again
294 and less klunkily) and do not append `-exited' to the buffer name.
295 Further, the behavior of `(ess-cleanup)', called from ess-quit,
296 now depends on the new customizable variable
297 `ess-S-quit-kill-buffers-p' which defaults to `nil'.
298 Consequently, the question _"Delete all buffers associated with
299 ..?"_ will not be asked anymore by default.
301 * ESS[SAS] - ess-ebcdic-to-ascii-search-and-replace will now work
302 with the `recode' application as well which is available on many
305 * ESS[S] (incl. R): Name completion for slots of S4 objects now
308 Changes/New Features in 5.2.4:
309 * The documentation now includes an overview of how to use the emacs
310 TAGS facility for S functions. (The distribution also used to
311 contain a directory `etc/other/Tags' where a ~1990 version of
312 `etags.c' was distributed; this is no longer relevant and so has
315 * ESS[SAS] - When you are working with EBCDIC files on an ASCII
316 platform, .log NOTEs may display as gibberish since the EBCDIC
317 characters are not converted to ASCII prior to their display. So,
318 the function ess-ebcdic-to-ascii-search-and-replace is provided for
319 convenience and is bound to `C-F11'. This function requires the
320 `dd' command (only available on unix or unix-like platforms).
322 * ESS: Completion of object names is now always done dynamically
323 rather than allowing the option of using a pre-computed database
324 (by `ess-create-object-name-db') since modern computers seem fast
325 enough for dynamic completion. (We expect few users, if any, have
326 been using the pre-computed database method.)
328 * ESS: object completion in iESS buffers running on Windows was very
329 slow (for GNU Emacs, but not XEmacs) and has now been fixed.
330 Further, it was more or less broken for all versions of S-plus 6.x,
331 and has been fixed to work everywhere but with the Windows' GUI of
332 S-plus. The list of objects now shows unique names also when an
333 object appears more than once in the search path.
335 * ESS[R]: Completion of object names now also includes those
338 Changes/New Features in 5.2.3:
339 * ESS: When new inferior ESS processes are created, by default they
340 will replace the current buffer (this restores behavior from pre
341 5.2.0). If you wish new ESS processes to start in another window
342 of the current frame, set inferior-ess-same-window to nil.
344 * New variables inferior-Splus-args and inferior-R-args provide a
345 way to pass command line arguments to starting S and R processes.
347 Changes/New Features in 5.2.2:
348 * bug-fixes for 5.2.1 (require 'executable), html docs, etc.
350 * ess-lisp-directory/../doc/info added to Info-directory-list if
351 ess-info not found by info
353 * ESS[R]: If you have other versions of R on your exec-path, such as
354 "R-1.8.1" with Unix or "rw1081" with Windows, ESS will find them
355 and create appropriate functions, such as `M-x R-1.8.1' or `M-x
356 rw1081', for calling them. By default only Unix programs
357 beginning "R-1" and "R-2" and Windows programs parallel to the
358 version of R in your exec-path will be found, but see
359 ess-r-versions and ess-rterm-versions for ways to find other
362 * ESS[R]: Other versions of R, such as "R-1.8.1" on Unix and
363 "rw1081" on Windows, are added to the "ESS / Start Process /
366 * ESS[S]: If you have other versions of S-Plus on your Windows
367 computer, such as S-Plus 6.1 or S-Plus 4.5, ESS will find them and
368 create appropriate functions, such as `M-x splus61', for calling
369 the console version (Sqpe) inside an emacs buffer. By default only
370 programs installed in the default location will be found, but see
371 ess-SHOME-versions for ways to find other versions of S-Plus.
373 * ESS[S]: Other versions of Sqpe on Windows, such as "splus61", are
374 added to the "ESS / Start Process / Other" menu.
376 * ESS[R]: (bug fix) ess-quit (bound to `C-c C-q') should now quit the
377 inferior R process, when issued from either the inferior buffer,
380 Changes/New Features in 5.2.1:
381 * ESS[S] (R and S-plus): now have toolbar support with icons to
382 evaluate code in the inferior process or to switch there. This
383 code is experimental and likely to change as XEmacs/Emacs issues
384 get resolved. The toolbar should be enabled if your Emacs displays
385 images, but can be disabled with the variable ess-use-toolbar.
386 Thanks to David Smith from Insightful for the S-plus logo.
388 * ESS[SAS]: ess-sas-graph-view (`F12') enhanced; you can specify
389 external file viewers for each graphics file type via the alist
390 ess-sas-graph-view-viewer-alist; also .jpg/.gif are now handled by
391 image-mode on XEmacs, if available, otherwise by graphics
394 Changes/New Features in 5.2.0:
395 * ESS[BUGS]: new info documentation! now supports interactive
396 processing thanks to Aki Vehtari (mailto:Aki.Vehtari@hut.fi); new
397 architecture-independent unix support as well as support for BUGS
400 * ESS[SAS]: convert .log to .sas with ess-sas-transcript; info
401 documentation improved; Local Variable bug fixes; SAS/IML
402 statements/functions now highlighted; files edited remotely by
403 ange-ftp/EFS/tramp are recognized and pressing SUBMIT opens a
404 buffer on the remote host via the local variable
405 ess-sas-shell-buffer-remote-init which defaults to "ssh"; changed
406 the definition of the variable ess-sas-edit-keys-toggle to boolean
407 rather than 0/1; added the function ess-electric-run-semicolon
408 which automatically reverse indents lines containing only "run;";
409 `C-F1' creates MS RTF portrait from the current buffer; `C-F2'
410 creates MS RTF landscape from the current buffer; `C-F9' opens a
411 SAS DATASET with PROC INSIGHT rather than PROC FSVIEW; "inferior"
412 aliases for SAS batch: `C-c C-r' for submit region, `C-c C-b' for
413 submit buffer, `C-c C-x' for goto .log; `C-c C-y' for goto .lst
415 * ESS[S]: Pressing underscore ("_") once inserts " <- " (as before);
416 pressing underscore twice inserts a literal underscore. To stop
417 this smart behaviour, add "(ess-smart-underscore nil)" to your
418 .emacs after ess-site has been loaded;
419 ess-dump-filename-template-proto (new name!) now can be customized
420 successfully (for S language dialects); Support for Imenu has been
421 improved; set ess-imenu-use-S to non-nil to get an "Imenu-S" item
422 on your menubar; ess-help: Now using nice underlines (instead of
425 * ESS[R]: After (require 'essa-r), `M-x ess-r-var' allows to load
426 numbers from any Emacs buffer into an existing *R* process; `M-x
427 ess-rdired' gives a "directory editor" of R objects; fixed
428 ess-retr-lastvalue-command, i.e. .Last.value bug (thanks to David
431 * ESS: Support for creating new window frames has been added to ESS.
432 Inferior ESS processes can be created in dedicated frames by
433 setting inferior-ess-own-frame to t. ESS help buffers can also
434 open in new frames; see the documentation for ess-help-own-frame
435 for details. (Thanks to Kevin Rodgers for contributing code.)
437 Changes/New Features in 5.1.24:
438 * The version number is now correct even inside ESS/Emacs
440 Changes/New Features in 5.1.23:
441 * Minor more Makefile clean up.
443 Changes/New Features in 5.1.22:
444 * Besides info documentation, PDF and HTML documentation are also
445 provided (instead of built using "make") and available on the web
446 as well; see ESS web page (http://ess.r-project.org/) and StatLib
447 (http://lib.stat.cmu.edu/general/ESS/doc)
449 * Now that info documentation is available, the README.* files are
450 no longer supported. However, they are still distributed for what
453 * ESS is now an XEmacs package! See XEmacs Installation HOWTO
454 (http://www.xemacs.org/Install/index.html) for details
455 (specifically, items 10-15).
457 * ESS[SAS]: more user-friendly enhancements for remote SAS batch
458 jobs with Kermit file transfers (LOG and OUTPUT function key
459 features now supported). Multiple shells now supported so you can
460 run SAS on different computers from different buffers by setting
461 the buffer-local variable ess-sas-shell-buffer to unique buffer
464 * Major re-vamping of Makefile/Makeconf.
466 Changes/New Features in 5.1.21:
467 * ESS[SAS]: info documentation now available!, see ESS->Help for
468 SAS; `F12' opens GSASFILE nearest point for viewing either within
469 emacs, when available, or via an external viewer; more syntax
470 highlighting keywords; more enhancements for remote SAS batch jobs
471 with Kermit; new framework for remote SAS interactive jobs, see
474 * ESS[S]: info documentation now available!, see ESS->Help for the S
477 * Makefile: tag now independent of rel; info files made by
478 doc/Makefile and installed in new info sub-directory
480 Changes/New Features in 5.1.20:
481 * New `options()$STERM' in the S dialects (S, S-Plus, R). The S
482 program can determine the environment in which it is currently
483 running. ESS sets the option to `iESS' or `ddeESS' when it starts
484 an S language process. We recommend other specific values for S
485 language processes that ESS does not start.
487 * New `ess-mouse-me' function, assigned to S-mouse-3 by default.
488 User may click on a word or region and then choose from the menu
489 to display the item, or a summary, or a plot, etc. This feature
490 is still under development.
492 * GNU Emacs 21.1 is now supported (fixed for S dialects, SAS & BUGS),
493 (some from Stephen Eglen).
495 * XEmacs 21.x is now supported (fixed w32-using-nt bug)
497 * XEmacs on Win (NT) is better supported.
499 * Workaround for bug in Sqpe+6 (S-PLUS 6 for Win).
501 * should now work even when imenu is not available (for old
504 * ESS[SAS]: XEmacs-Imenu fix; `C-TAB' is globalized along with your
505 function-key definitions, if specified; you can specify your SAS
506 library definitions outside of autoexec.sas for ess-sas-data-view
507 with SAS code placed in the variable ess-sas-data-view-libname,
508 also the dataset name is defaulted to the nearest permanent dataset
509 to point; Speedbar support now works for permanent datasets, please
510 ignore first./last.; new font-locking is now the default with more
511 improvements for font-locking PROCs, macro statements, * ; and %* ;
512 comments; you can toggle sas-log-mode with `F10' which will
513 font-lock your .log (if it isn't too big); submit remote .sas
514 files accessed with ange-ftp, EFS or Tramp (Kermit is
515 experimental) by setting ess-sas-submit-method to 'sh;
516 ess-sas-submit-command and ess-sas-submit-command-options are
517 buffer-local so you can have local file variable sections at the
518 end of your .sas files to request different executables or specify
519 special options and the local file variables are re-read at submit
520 instead of only at file open so that if you make a change it is
521 picked up immediately;
523 * ESS[BUGS]: font-lock with `in' fixed.
525 * for STATA: font-lock bug fixed.
527 * for Rd mode: `C-c C-v' and `switch-process' in menu. further,
528 `C-c C-f' prefix (Rd-font) for inserting or surrounding a word by
529 things such as \code{.}, \code{\link{.}}, \emph{.} etc.
531 * new functions (ess-directory-function) and (ess-narrow-to-defun)
532 ess-directory <-> default-directory logic (Jeff Mincy).
534 * Re-organized Makefile and fixed a few bugs.
536 Changes/New Features in 5.1.19:
537 * S+6 now supported (Tony Rossini (Unix) and Rich Heiberger
540 * New BUGS support through ESS[BUGS] mode (Rodney Sparapani)
541 Templates assist you in writing .bug and .cmd code (.cmd and .log
542 are replaced by .bmd and .bog to avoid emacs extension collisions).
543 Substitution" parameters facilitate "automagic" generation of
544 data...in" and "init...in" filenames, "const N=" from your data
545 file and "monitor()/stats()" commands. Activated by pressing
548 * Fixes for `ess-smart-underscore' SAS breakage (Rich Heiberger)
550 * You can change between PC and Unix, local and global SAS
551 function-key definitions interactively (Rich Heiberger)
553 * `C-Submit' a highlighted region to SAS batch (Rodney Sparapani)
555 * New and improved SAS syntax highlighting (Rodney Sparapani) To get
556 the new functionality, set ess-sas-run-make-regexp to nil. Also
557 available in .log files via `F10'.
559 * Open a permanent SAS dataset for viewing via `F9' (Rodney
560 Sparapani) You must have the library defined in autoexec.sas for
563 * User-friendly defaults for `sas-program',
564 `ess-sas-batch-pre-command' and `ess-sas-batch-post-command' as
565 well Customize support for these and other ESS[SAS] variables
568 * `ess-sas-suffix-2' now defaults to .dat via `F11' (Rodney
571 * Emacs/XEmacs, Unix/Windows issues collectively handled in
574 * defadvice solves problem of missing *ESS* (thanks to Jeff Mincy)
576 * Improved manual a bit by including things that were only in
579 Changes/New Features in 5.1.18:
580 * New `ess-smart-underscore' function, now assigned to "_" by
581 default. Inserts `ess-S-assign' (customizable " <- "), unless
582 inside string and comments where plain "_" is used instead. (MM)
584 * Fixes for longstanding interactive SAS breakage (RMH)
586 Changes/New Features in 5.1.17:
587 * Documentation for Windows Installation (Rich Heiberger)
589 * removal of ess-vars, finalization of customize support (in the
590 sense that there is no more use of ess-vars, but that we need to
591 fix ess-cust) (AJ Rossini)
593 * Many small (and large) fixes/contributions (MMaechler)
595 * addition of the "S-equal" variable and provide `M-x
596 ess-add-MM-keys' a way to remap "_" to `ess-S-assign', typically "
597 <- ", but customizable. (MMaechler)
599 Changes/New Features in 5.1.16:
604 Changes/New Features in 5.1.15:
607 Changes/New Features in 5.1.14:
608 * Yet more fixes to SAS mode, (Rich Heiberger and Rodney Sparapani)
610 * Customize support (for most Emacsen which support it) (AJRossini)
612 * ARC and ViSta support out of the box, and fixes for XLispStat
615 Changes/New Features in 5.1.13:
616 * Version numbering finally all depending on the ./VERSION file,
617 thanks to Martin Maechler.
619 * Yet more fixes to SAS mode, thanks to Rich Heiberger.
621 Changes/New Features in 5.1.12:
622 * Splus 5.1 stabilized, thanks to Martin Maechler, Bill Venables,
623 Chuck Taylor, and others.
625 * More fixes to SAS mode, thanks to Rodney Sparapani and Rich
628 Changes/New Features in 5.1.11:
629 * More fixes to Stata mode, thanks to Brendan Halpin
630 (mailto:brendan@essex.ac.uk).
632 * fixed bugs in ESS-elsewhere, thanks to many testers
634 * README.SPLUS4WIN has DETAILED instructions for S-PLUS 2000, thanks
635 to David Brahm (mailto:brahm@alum.mit.edu).
637 * Fixes to SAS mode, thanks to Rodney Sparapani
639 Changes/New Features in 5.1.10:
640 * More fixes to Stata mode
642 * primitive generic version of ESS-elsewhere
644 * Small fixes to SAS/Stata.
646 Changes/New Features in 5.1.9:
649 * Literate Data Analysis using Noweb works
651 Changes/New Features in 5.1.8:
654 * R documentation mode defaults changed
656 Changes/New Features in 5.1.2:
657 * able to use inferior iESS mode to communicate directly with a
658 running S-Plus 4.x process using the Microsoft DDE protocol. We
659 use the familiar (from Unix ESS) `C-c C-n' and related key
660 sequences to send lines from the S-mode file to the inferior S
661 process. We continue to edit S input files in ESS[S] mode and
662 transcripts of previous S sessions in ESS Transcript mode. All
663 three modes know the S language, syntax, and indentation patterns
664 and provide the syntactic highlighting that eases the programming