README

   1 1 General Information: README
   2 *****************************
   3
   4 This is the README file for the distribution of ESS version
   5
   6    5.2.9
   7
   8    ESS is a GNU Emacs and XEmacs mode for interactive statistical
   9 programming and data analysis.  Languages supported: the S family (S
  10 3/4, S-PLUS 3/4/5/6/7, and R), SAS, XLispStat, Stata and BUGS.
  11 Installation help can be found in sections for both Unix and Windows.
  12 For INSTALLATION, see way below.
  13
  14 ESS grew out of the desire for bug fixes and extensions to S-mode and
  15 SAS-mode as well as a consistent union of their features in one package.
  16
  17    The current development team is led by Martin Maechler since August
  18 2004. Former project leader A.J. (Tony) Rossini
  19 (<rossini@blindglobe.net>) did the initial port to XEmacs and has been
  20 the primary coder.  Martin Maechler (<maechler@stat.math.ethz.ch>) and
  21 Kurt Hornik (<Kurt.Hornik@R-project.org>) have assisted with S-PLUS,
  22 S4, R, and XLispStat.  Stephen Eglen (<stephen@gnu.org>) has worked
  23 mostly on R support.  Richard M. Heiberger (<rmh@temple.edu>) has
  24 assisted with S-PLUS and S4 development for Windows.  Richard and
  25 Rodney A. Sparapani (<rsparapa@mcw.edu>) have done much of the work
  26 implementing interactive SAS (iESS[SAS]) and batch SAS (ESS[SAS])
  27 support.
  28
  29    We are grateful to the previous developers of S-mode (Doug Bates, Ed
  30 Kademan, Frank Ritter, David M. Smith), SAS-mode (Tom Cook) and
  31 Stata-mode (Thomas Lumley).
  32
  33 1.1 License
  34 ===========
  35
  36 ESS is free software; you can redistribute it and/or modify it under
  37 the terms of the GNU General Public License as published by the Free
  38 Software Foundation; either version 2, or (at your option) any later
  39 version.
  40
  41    ESS is distributed in the hope that it will be useful, but WITHOUT
  42 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  43 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  44 in the file COPYING in the same directory as this file for more details.
  45
  46 1.2 New Features
  47 ================
  48
  49 Changes/New Features in 5.2.9:
  50    * ESS[R] for Windows:  the \ directory character bug with respect to
  51      ess-load-file has been eradicated.
  52
  53    * iESS[SAS]: `C-c C-r' and `C-c C-b' once again work as intended and
  54      documented.
  55
  56    * ESS[S]: M-x ess-fix-EQ-assign is a bit more agressive.
  57
  58    * ESS[S]: Imenu now also shows setAs(), etc.
  59
  60    * ESS[R]: R function pattern enhanced with underlying code such that
  61      `M-C-a' (`ess-beginning-of-function') etc now work for many more
  62      cases, including S4 method definitions.
  63
  64    * iESS[R]: myOwnhelp(1) no longer wrongly triggers help(1).
  65
  66    * ESS[R]: Improved detection of bogus help buffers: valid help
  67      buffers containing with the string "no documentation"(e.g. contour)
  68      were being treated as bogus.
  69
  70    * ESS[R]: In R help buffers, if `options("help.try.all.packages" =
  71      TRUE)' then `?rlm' will list which packages rlm is defined in.
  72      This help  buffer is not bogus, but instead is now relabelled
  73      "*help[R](rlm in  packages)*".
  74
  75    * ESS[STA]: add "//" as comment starting character to syntax-table.
  76
  77    Changes/New Features in 5.2.8:
  78    * iESS: [Tab] completes *file* names "inside string" as in earlier
  79      (<= 5.2.3) ESS versions.
  80
  81    Changes/New Features in 5.2.7:
  82    * If you use Custom to change the variable ess-toolbar-items, the
  83      new toolbar is used in all subsequent ESS buffers.
  84
  85    * ESS[SAS]: new feature:  if ess-sas-log-max >0 and your .log grows
  86      to more than ess-sas-log-max bytes, just the first ess-sas-log-max
  87      bytes are refreshed; this is helpful when your .sas program
  88      generates lots of error messages and gets too big for emacs to
  89      display
  90
  91    * ESS[R/S]: `M-;' in R/S editing modes will now indent with either
  92      one or two hashes depending on context.
  93
  94    * ESS[R]: David Whiting's Sweave extensions (to 'noweb') are now
  95      available (from ess-swv.el loaded by default).
  96
  97    Changes/New Features in 5.2.6:
  98    * Removed non-ASCII characters in a few files.
  99
 100    * ESS[R]: now works better when UTF-8 locale is active; in
 101      particular, you get correct directional quotes in R's startup
 102      message  for R-devel (unstable development version of R 2.1.0)
 103      when using  environment variables LANGUAGE=en@quot
 104      LC_ALL=en_US.UTF-8
 105
 106    * ESS[SAS]: toggling of .log mode improved (`F10'); toggling of .lst
 107      mode now also available (`C-F10'); killing all buffers associated
 108      with .sas program no longer bound to `C-F10' since its a bit
 109      overzealous.
 110
 111    * S-Plus 7 for Windows is now recognized.
 112
 113    * ESS[S] (incl. R): in auto-fill mode, strings are not wrapped
 114      anymore.
 115
 116    * ESS[S] (incl. R): font-lock now correctly differs between R and S,
 117      e.g., for "_"; both now fontify warning(.) and S does terminate()
 118      additionally.
 119
 120    * Support for `bell' aka `beep' aka `ding' aka `alarm' in all
 121      inferior modes: When \a is output "to the the console" at the
 122      beginning of a line, the bell is rung.
 123
 124    Changes/New Features in 5.2.5:
 125    * ESS[R]: `C-c C-q' or `Quit S' from the menu now should work (again
 126      and less klunkily) and do not append `-exited' to the buffer name.
 127      Further, the behavior of `(ess-cleanup)', called from ess-quit,
 128      now depends on the new customizable variable
 129      `ess-S-quit-kill-buffers-p' which defaults to `nil'.
 130      Consequently, the question _"Delete all buffers associated with
 131      ..?"_ will not be asked anymore by default.
 132
 133    * ESS[SAS] - ess-ebcdic-to-ascii-search-and-replace will now work
 134      with the `recode' application as well which is available on many
 135      platforms
 136
 137    * ESS[S] (incl. R): Name completion for slots of S4 objects now
 138      works!
 139
 140    Changes/New Features in 5.2.4:
 141    * The documentation now includes an overview of how to use the emacs
 142      TAGS facility for S functions.  (The distribution also used to
 143      contain a directory `etc/other/Tags' where a ~1990 version of
 144      `etags.c' was distributed; this is no longer relevant and so has
 145      been deleted.)
 146
 147    * ESS[SAS] - When you are working with EBCDIC files on an ASCII
 148      platform, .log NOTEs may display as gibberish since the EBCDIC
 149      characters are not converted to ASCII prior to their display.  So,
 150      the function ess-ebcdic-to-ascii-search-and-replace is provided for
 151      convenience and is bound to `C-F11'.  This function requires the
 152      `dd' command (only available on unix or unix-like platforms).
 153
 154    * ESS: Completion of object names is now always done dynamically
 155      rather than allowing the option of using a pre-computed database
 156      (by `ess-create-object-name-db') since modern computers seem fast
 157      enough for dynamic completion.  (We expect few users, if any, have
 158      been using the pre-computed database method.)
 159
 160    * ESS: object completion in iESS buffers running on Windows was very
 161      slow (for GNU Emacs, but not XEmacs) and has now been fixed.
 162      Further, it was more or less broken for all versions of S-plus 6.x,
 163      and has been fixed to work everywhere but with the Windows' GUI of
 164      S-plus.  The list of objects now shows unique names also when an
 165      object appears more than once in the search path.
 166
 167    * ESS[R]: Completion of object names now also includes those
 168      starting with ".".
 169
 170    Changes/New Features in 5.2.3:
 171    * ESS: When new inferior ESS processes are created, by default they
 172      will replace the current buffer (this restores behavior from pre
 173      5.2.0). If you wish new ESS processes to start in another window
 174      of the current frame, set inferior-ess-same-window to nil.
 175
 176    * New variables inferior-Splus-args and inferior-R-args provide a
 177      way to pass command line arguments to starting S and R processes.
 178
 179    Changes/New Features in 5.2.2:
 180    * bug-fixes for 5.2.1 (require 'executable), html docs, etc.
 181
 182    * ess-lisp-directory/../doc/info added to Info-directory-list if
 183      ess-info not found by info
 184
 185    * ESS[R]: If you have other versions of R on your exec-path, such as
 186      "R-1.8.1" with Unix or "rw1081" with Windows, ESS will find them
 187      and create appropriate functions, such as `M-x R-1.8.1' or `M-x
 188      rw1081', for calling them.  By default only Unix programs
 189      beginning "R-1" and "R-2" and Windows programs parallel to the
 190      version of R in your exec-path will be found, but see
 191      ess-r-versions and ess-rterm-versions for ways to find other
 192      versions of R.
 193
 194    * ESS[R]: Other versions of R, such as "R-1.8.1" on Unix and
 195      "rw1081" on Windows, are added to the "ESS / Start Process /
 196      Other" menu.
 197
 198    * ESS[S]: If you have other versions of S-Plus on your Windows
 199      computer, such as S-Plus 6.1 or S-Plus 4.5, ESS will find them and
 200      create appropriate functions, such as `M-x splus61', for calling
 201      the console version (Sqpe) inside an emacs buffer.  By default only
 202      programs installed in the default location will be found, but see
 203      ess-SHOME-versions for ways to find other versions of S-Plus.
 204
 205    * ESS[S]: Other versions of Sqpe on Windows, such as "splus61", are
 206      added to the "ESS / Start Process / Other" menu.
 207
 208    * ESS[R]: (bug fix) ess-quit (bound to `C-c C-q') should now quit the
 209      inferior R process, when issued from either the inferior buffer,
 210      or from a .R buffer.
 211
 212    Changes/New Features in 5.2.1:
 213    * ESS[S] (R and S-plus): now have toolbar support with icons to
 214      evaluate code in the inferior process or to switch there.  This
 215      code is experimental and likely to change as XEmacs/Emacs issues
 216      get resolved. The toolbar should be enabled if your Emacs displays
 217      images, but can be disabled with the variable ess-use-toolbar.
 218      Thanks to David Smith from Insightful for the S-plus logo.
 219
 220    * ESS[SAS]: ess-sas-graph-view (`F12') enhanced; you can specify
 221      external file viewers for each graphics file type via the alist
 222      ess-sas-graph-view-viewer-alist; also .jpg/.gif are now handled by
 223      image-mode on XEmacs, if available, otherwise by graphics
 224      primitives as before
 225
 226    Changes/New Features in 5.2.0:
 227    * ESS[BUGS]:  new info documentation!  now supports interactive
 228      processing thanks to Aki Vehtari (mailto:Aki.Vehtari@hut.fi); new
 229      architecture-independent unix support as well as support for BUGS
 230      v. 0.5
 231
 232    * ESS[SAS]:  convert .log to .sas with ess-sas-transcript; info
 233      documentation improved; Local Variable bug fixes; SAS/IML
 234      statements/functions now highlighted; files edited remotely by
 235      ange-ftp/EFS/tramp are recognized and pressing SUBMIT opens a
 236      buffer on the remote host via the local variable
 237      ess-sas-shell-buffer-remote-init which defaults to "ssh"; changed
 238      the definition of the variable ess-sas-edit-keys-toggle to boolean
 239      rather than 0/1; added the function ess-electric-run-semicolon
 240      which automatically reverse indents lines containing only "run;";
 241      `C-F1' creates MS RTF portrait from the current buffer; `C-F2'
 242      creates MS RTF landscape from the current buffer; `C-F9' opens a
 243      SAS DATASET with PROC INSIGHT rather than PROC FSVIEW; "inferior"
 244      aliases for SAS batch:  `C-c C-r' for submit region, `C-c C-b' for
 245      submit buffer, `C-c C-x' for goto .log; `C-c C-y' for goto .lst
 246
 247    * ESS[S]: Pressing underscore ("_") once inserts " <- " (as before);
 248      pressing underscore twice inserts a literal underscore.  To stop
 249      this smart behaviour, add "(ess-toggle-underscore nil)" to your
 250      .emacs after ess-site has been loaded;
 251      ess-dump-filename-template-proto (new name!) now can be customized
 252      successfully (for S language dialects); Support for Imenu has been
 253      improved; set ess-imenu-use-S to non-nil to get an "Imenu-S" item
 254      on your menubar; ess-help: Now using nice underlines (instead of
 255      `nuke-* ^H_')
 256
 257    * ESS[R]:  After (require 'essa-r), `M-x ess-r-var' allows to load
 258      numbers from any Emacs buffer into an existing *R* process; `M-x
 259      ess-rdired' gives a "directory editor" of R objects; fixed
 260      ess-retr-lastvalue-command, i.e. .Last.value bug (thanks to David
 261      Brahm)
 262
 263    * ESS: Support for creating new window frames has been added to ESS.
 264      Inferior ESS processes can be created in dedicated frames by
 265      setting inferior-ess-own-frame to t.  ESS help buffers can also
 266      open in new frames; see the documentation for ess-help-own-frame
 267      for details.  (Thanks to Kevin Rodgers for contributing code.)
 268
 269    Changes/New Features in 5.1.24:
 270    * The version number is now correct even inside ESS/Emacs
 271
 272    Changes/New Features in 5.1.23:
 273    * Minor more Makefile clean up.
 274
 275    Changes/New Features in 5.1.22:
 276    * Besides info documentation, PDF and HTML documentation are also
 277      provided (instead of built using "make") and available on the web
 278      as well; see ESS web page (http://ess.r-project.org/) and StatLib
 279      (http://lib.stat.cmu.edu/general/ESS/doc)
 280
 281    * Now that info documentation is available, the README.* files are
 282      no longer supported.  However, they are still distributed for what
 283      it's worth.
 284
 285    * ESS is now an XEmacs package!  See XEmacs Installation HOWTO
 286      (http://www.xemacs.org/Install/index.html) for details
 287      (specifically, items 10-15).
 288
 289    * ESS[SAS]: more user-friendly enhancements for remote SAS batch
 290      jobs with Kermit file transfers (LOG and OUTPUT function key
 291      features now supported).  Multiple shells now supported so you can
 292      run SAS on different computers from different buffers by setting
 293      the buffer-local variable ess-sas-shell-buffer to unique buffer
 294      names.
 295
 296    * Major re-vamping of Makefile/Makeconf.
 297
 298    Changes/New Features in 5.1.21:
 299    * ESS[SAS]: info documentation now available!, see ESS->Help for
 300      SAS; `F12' opens GSASFILE nearest point for viewing either within
 301      emacs, when available, or via an external viewer; more syntax
 302      highlighting keywords; more enhancements for remote SAS batch jobs
 303      with Kermit; new framework for remote SAS interactive jobs, see
 304      ess-remote
 305
 306    * ESS[S]: info documentation now available!, see ESS->Help for the S
 307      family
 308
 309    * Makefile: tag now independent of rel; info files made by
 310      doc/Makefile and installed in new info sub-directory
 311
 312    Changes/New Features in 5.1.20:
 313    * New `options()$STERM' in the S dialects (S, S-Plus, R).  The S
 314      program can determine the environment in which it is currently
 315      running.  ESS sets the option to `iESS' or `ddeESS' when it starts
 316      an S language process.  We recommend other specific values for S
 317      language processes that ESS does not start.
 318
 319    * New `ess-mouse-me' function, assigned to S-mouse-3 by default.
 320      User may click on a word or region and then choose from the menu
 321      to display the item, or a summary, or a plot, etc.  This feature
 322      is still under development.
 323
 324    * GNU Emacs 21.1 is now supported (fixed for S dialects, SAS & BUGS),
 325      (some from Stephen Eglen).
 326
 327    * XEmacs 21.x is now supported (fixed w32-using-nt bug)
 328
 329    * XEmacs on Win (NT) is better supported.
 330
 331    * Workaround for bug in Sqpe+6 (S-PLUS 6 for Win).
 332
 333    * should now work even when imenu is not available (for old
 334      XEmacsen).
 335
 336    * ESS[SAS]: XEmacs-Imenu fix; `C-TAB' is globalized along with your
 337      function-key definitions, if specified; you can specify your SAS
 338      library definitions outside of autoexec.sas for ess-sas-data-view
 339      with SAS code placed in the variable ess-sas-data-view-libname,
 340      also the dataset name is defaulted to the nearest permanent dataset
 341      to point; Speedbar support now works for permanent datasets, please
 342      ignore first./last.; new font-locking is now the default with more
 343      improvements for font-locking PROCs, macro statements, * ; and %* ;
 344      comments; you can toggle sas-log-mode with `F10' which will
 345      font-lock your .log (if it isn't too big); submit remote .sas
 346      files accessed with ange-ftp, EFS or Tramp (Kermit is
 347      experimental) by setting ess-sas-submit-method to 'sh;
 348      ess-sas-submit-command and ess-sas-submit-command-options are
 349      buffer-local so you can have local file variable sections at the
 350      end of your .sas files to request different executables or specify
 351      special options and the local file variables are re-read at submit
 352      instead of only at file open so that if you make a change it is
 353      picked up immediately;
 354
 355    * ESS[BUGS]: font-lock with `in' fixed.
 356
 357    * for STATA: font-lock bug fixed.
 358
 359    * for Rd mode: `C-c C-v' and `switch-process' in menu.  further,
 360      `C-c C-f' prefix (Rd-font) for inserting or surrounding a word by
 361      things such as \code{.}, \code{\link{.}}, \emph{.} etc.
 362
 363    * new functions (ess-directory-function) and (ess-narrow-to-defun)
 364      ess-directory <-> default-directory logic (Jeff Mincy).
 365
 366    * Re-organized Makefile and fixed a few bugs.
 367
 368    Changes/New Features in 5.1.19:
 369    * S+6 now supported (Tony Rossini (Unix) and Rich Heiberger
 370      (Windows))
 371
 372    * New BUGS support through ESS[BUGS] mode (Rodney Sparapani)
 373      Templates assist you in writing .bug and .cmd code (.cmd and .log
 374      are replaced by .bmd and .bog to avoid emacs extension collisions).
 375      Substitution" parameters facilitate "automagic" generation of
 376      data...in" and "init...in" filenames, "const N=" from your data
 377      file and "monitor()/stats()" commands.  Activated by pressing
 378      `F12'.
 379
 380    * Fixes for `ess-smart-underscore' SAS breakage (Rich Heiberger)
 381
 382    * You can change between PC and Unix, local and global SAS
 383      function-key definitions interactively (Rich Heiberger)
 384
 385    * `C-Submit' a highlighted region to SAS batch (Rodney Sparapani)
 386
 387    * New and improved SAS syntax highlighting (Rodney Sparapani) To get
 388      the new functionality, set ess-sas-run-make-regexp to nil.  Also
 389      available in .log files via `F10'.
 390
 391    * Open a permanent SAS dataset for viewing via `F9' (Rodney
 392      Sparapani) You must have the library defined in autoexec.sas for
 393      it to work.
 394
 395    * User-friendly defaults for `sas-program',
 396      `ess-sas-batch-pre-command' and `ess-sas-batch-post-command' as
 397      well Customize support for these and other ESS[SAS] variables
 398      (Rodney Sparapani)
 399
 400    * `ess-sas-suffix-2' now defaults to .dat via `F11' (Rodney
 401      Sparapani)
 402
 403    * Emacs/XEmacs, Unix/Windows issues collectively handled in
 404      ess-emcs.el
 405
 406    * defadvice solves problem of missing *ESS* (thanks to Jeff Mincy)
 407
 408    * Improved manual a bit by including things that were only in
 409      `README'.
 410
 411    Changes/New Features in 5.1.18:
 412    * New `ess-smart-underscore' function, now assigned to "_" by
 413      default.  Inserts `ess-S-assign' (customizable " <- "), unless
 414      inside string and comments where plain "_" is used instead. (MM)
 415
 416    * Fixes for longstanding interactive SAS breakage (RMH)
 417
 418    Changes/New Features in 5.1.17:
 419    * Documentation for Windows Installation (Rich Heiberger)
 420
 421    * removal of ess-vars, finalization of customize support (in the
 422      sense that there is no more use of ess-vars, but that we need to
 423      fix ess-cust) (AJ Rossini)
 424
 425    * Many small (and large) fixes/contributions (MMaechler)
 426
 427    * addition of the "S-equal" variable and provide `M-x
 428      ess-add-MM-keys' a way to remap "_" to `ess-S-assign', typically "
 429      <- ", but customizable. (MMaechler)
 430
 431    Changes/New Features in 5.1.16:
 432    * BUG FIXES
 433
 434    * Better SAS support
 435
 436    Changes/New Features in 5.1.15:
 437    * BUG FIXES
 438
 439    Changes/New Features in 5.1.14:
 440    * Yet more fixes to SAS mode, (Rich Heiberger and Rodney Sparapani)
 441
 442    * Customize support (for most Emacsen which support it) (AJRossini)
 443
 444    * ARC and ViSta support out of the box, and fixes for XLispStat
 445      (AJRossini)
 446
 447    Changes/New Features in 5.1.13:
 448    * Version numbering finally all depending on the ./VERSION file,
 449      thanks to Martin Maechler.
 450
 451    * Yet more fixes to SAS mode, thanks to Rich Heiberger.
 452
 453    Changes/New Features in 5.1.12:
 454    * Splus 5.1 stabilized, thanks to Martin Maechler, Bill Venables,
 455      Chuck Taylor, and others.
 456
 457    * More fixes to SAS mode, thanks to Rodney Sparapani and Rich
 458      Heiberger.
 459
 460    Changes/New Features in 5.1.11:
 461    * More fixes to Stata mode, thanks to Brendan Halpin
 462      (mailto:brendan@essex.ac.uk).
 463
 464    * fixed bugs in ESS-elsewhere, thanks to many testers
 465
 466    * README.SPLUS4WIN has DETAILED instructions for S-PLUS 2000, thanks
 467      to David Brahm (mailto:brahm@alum.mit.edu).
 468
 469    * Fixes to SAS mode, thanks to Rodney Sparapani
 470
 471    Changes/New Features in 5.1.10:
 472    * More fixes to Stata mode
 473
 474    * primitive generic version of ESS-elsewhere
 475
 476    * Small fixes to SAS/Stata.
 477
 478    Changes/New Features in 5.1.9:
 479    * Stata mode works
 480
 481    * Literate Data Analysis using Noweb works
 482
 483    Changes/New Features in 5.1.8:
 484    * Bug fixes
 485
 486    * R documentation mode defaults changed
 487
 488    Changes/New Features in 5.1.2:
 489    * able to use inferior iESS mode to communicate directly with a
 490      running S-Plus 4.x process using the Microsoft DDE protocol.  We
 491      use the familiar (from Unix ESS) `C-c C-n' and related key
 492      sequences to send lines from the S-mode file to the inferior S
 493      process.  We continue to edit S input files in ESS[S] mode and
 494      transcripts of previous S sessions in ESS Transcript mode.  All
 495      three modes know the S language, syntax, and indentation patterns
 496      and provide the syntactic highlighting that eases the programming
 497      tasks.
 498
 499 1.3 Current Features
 500 ====================
 501
 502    * Languages Supported:
 503         * S family (S 3/4, S-PLUS 3.x/4.x/5.x/6.x/7.x, and R)
 504
 505         * SAS
 506
 507         * BUGS
 508
 509         * Stata
 510
 511         * XLispStat including Arc and ViSta
 512
 513    * Editing source code (S family, SAS, BUGS, XLispStat)
 514         * Syntactic indentation and highlighting of source code
 515
 516         * Partial evaluation of code
 517
 518         * Loading and error-checking of code
 519
 520         * Source code revision maintenance
 521
 522         * Batch execution (SAS, BUGS)
 523
 524         * Use of imenu to provide links to appropriate functions
 525
 526    * Interacting with the process (S family, SAS, XLispStat)
 527         * Command-line editing
 528
 529         * Searchable Command history
 530
 531         * Command-line completion of S family object names and file
 532           names
 533
 534         * Quick access to object lists and search lists
 535
 536         * Transcript recording
 537
 538         * Interface to the help system
 539
 540    * Transcript manipulation (S family, XLispStat)
 541         * Recording and saving transcript files
 542
 543         * Manipulating and editing saved transcripts
 544
 545         * Re-evaluating commands from transcript files
 546
 547    * Help File Editing (R)
 548         * Syntactic indentation and highlighting of source code.
 549
 550         * Sending Examples to running ESS process.
 551
 552         * Previewing
 553
 554 1.4 Stability
 555 =============
 556
 557 Versions 5.2.x are meant to be release-quality versions.  While some
 558 new features are being introduced, we are cleaning up and improving the
 559 interface.  We know about some remaining documentation inconsistencies.
 560 Patches or suggested fixes with bug reports are much appreciated!
 561
 562 1.5 Requirements
 563 ================
 564
 565 ESS has been tested with
 566
 567    * R >=0.49
 568
 569    * S-PLUS 3.3-4, 4.5, 5.0-1, 6.0-2, 7.0, 2000
 570
 571    * S4
 572
 573    * SAS >=6.12
 574
 575    * BUGS 0.5, 0.603
 576
 577    * Stata >=6.0
 578
 579    * XLispStat >=3.50
 580
 581    on the following platforms
 582
 583    * Linux (all)
 584
 585    * Solaris/SunOS (all)
 586
 587    * Microsoft Windows 95/98/NT/2000/XP (R, SPLUS 4.5/6.0-2/7.0/2000,
 588      SAS and BUGS)
 589
 590    * Apple Mac OS (SAS for OS 9 and R for OS X)
 591
 592    with the following versions of emacs
 593
 594    * GNU Emacs 20.3-7, 21.1, 21.3-4, 22.0.50-pretesting
 595
 596    * XEmacs 21.0, 21.1.13-14, 21.4.0-8, 21.4.9-13(1), 21.4.14-15,
 597      21.4.17, 21.5.18
 598
 599    ---------- Footnotes ----------
 600
 601    (1) require the files.el patch to revert-buffer for the Local
 602 Variables updating problem
 603
 604 1.6 Getting the Latest Version
 605 ==============================
 606
 607 The latest released version of ESS is always available on the web at:
 608 ESS web page (http://ess.r-project.org) or StatLib
 609 (http://lib.stat.cmu.edu/general/ESS/)
 610
 611    The latest development version of ESS is available via
 612 `https://svn.R-project.org/ESS/', the ESS Subversion repository.  If
 613 you have a Subversion client (see `http://subversion.tigris.org/'), you
 614 can download the sources using:
 615      % svn checkout https://svn.r-project.org/ESS/trunk PATH
 616    which will put the ESS files into directory PATH.  Later, within
 617 that directory, `svn update' will bring that directory up to date.
 618 Windows-based tools such as TortoiseSVN are also available for
 619 downloading the files.  Alternatively, you can browse the sources with a
 620 web browser at: ESS SVN site (https://svn.r-project.org/ESS/trunk).
 621 However, please use a subversion client instead to minimize the load
 622 when retrieving.
 623
 624    If you remove other versions of ESS from your emacs load-path, you
 625 can then use the development version by adding the following to .emacs:
 626
 627      (load "/path/to/ess-svn/lisp/ess-site.el")
 628
 629    Note that https is required, and that the SSL certificate for the
 630 Subversion server of the R project is
 631
 632      Certificate information:
 633       - Hostname: svn.r-project.org
 634       - Valid: from Jul 16 08:10:01 2004 GMT until Jul 14 08:10:01 2014 GMT
 635       - Issuer: Department of Mathematics, ETH Zurich, Zurich, Switzerland, CH
 636       - Fingerprint: c9:5d:eb:f9:f2:56:d1:04:ba:44:61:f8:64:6b:d9:33:3f:93:6e:ad
 637
 638 (currently, there is no "trusted certificate").  You can accept this
 639 certificate permanently and will not be asked about it anymore.
 640
 641 1.7 Installation (from tar file)
 642 ================================
 643
 644 We now discuss installation, which might happen under Unix or Microsoft
 645 Windows.  First, we discuss Unix installation.  *Note Unix
 646 installation::.
 647
 648    For Microsoft Windows Installation please skip to the *Note
 649 Microsoft Windows installation::.
 650
 651 1.8 Unix installation
 652 =====================
 653
 654   1. cd to a directory where you want to install ESS, creating it if
 655      necessary.  This directory will be referred to below as ESSDIR.
 656
 657   2. Retrieve the latest version from ESS downloads area
 658      (http://ess.r-project.org/downloads/ess) to ESSDIR.
 659
 660   3. Decompress/unarchive the files from the disribution.
 661           gunzip ess-VERSION.tar.gz
 662           tar xvf ess-VERSION.tar
 663
 664           (or: `gunzip < ess-VERSION.tar.gz | tar xvf -' ).
 665           (or using GNU tar:  `tar zxvf ess-VERSION.tar.gz').
 666
 667      The `tar' command will create the subdirectory ess-VERSION and
 668      unarchive the files there.
 669
 670   4. Edit the file `ESSDIR/ess-VERSION/lisp/ess-site.el' as explained
 671      in the comments section of that file.
 672
 673   5.  Add the line
 674           (load "ESSDIR/ess-VERSION/lisp/ess-site")
 675      to your user or system installation file (GNU Emacs uses
 676      `$HOME/.emacs' and XEmacs uses `$HOME/.xemacs/init.el' for the
 677      user initialization file.  GNU Emacs uses default.el or
 678      site-init.el and XEmacs uses site-start.el for the system
 679      installation file).
 680
 681      Alternatively, if ess-site.el is in your current Lisp path, you
 682      can do:
 683           (require 'ess-site)
 684      to configure emacs for ESS.
 685
 686   6. That's it!  If you are installing just a local copy of ESS for
 687      yourself, ESS is now ready to be used.  (The remaining step below
 688      is for advanced installation.)  To edit statistical programs, load
 689      the files with the requiste extensions (".sas" for SAS, ".S" for
 690      S-PLUS, ".R" for R, and ".lsp" for XLispStat).  To start a
 691      statistical process within Emacs, such as R, type `M-x R'.
 692
 693   7. (OPTIONAL) READ THIS ITEM THOROUGHLY BEFORE STARTING:
 694
 695      If you want to place the compiled files in other locations edit
 696      the LISPDIR and INFODIR entries in `Makeconf' in the
 697      ESSDIR/ess-VERSION directory (if you are using XEmacs, then you
 698      also need to edit the EMACS entry as follows:  EMACS=xemacs).
 699
 700      You can compile those files by:
 701           make all
 702
 703      When that completes successfully, install the compiled files:
 704           make install
 705
 706      This will install the compiled info files and lisp files.  If you
 707      are an XEmacs user, then you should be done.  If not, then you may
 708      have to edit/create the file `dir' that is found in the directory
 709      specified by `INFODIR': see the sample `dir' in
 710      ESSDIR/ess-VERSION/doc/info.  If `dir' does not exist in
 711      `INFODIR', then the sample `dir' will be installed.
 712
 713      _Note:_ ESS can be installed for XEmacs as an XEmacs package much
 714      more easily than what has been described anywhere above.  However,
 715      the latest ESS version will not be available at the same time as an
 716      XEmacs package; generally, it can take weeks or months to appear
 717      in the latter format.  For more information on installing ESS as
 718      an XEmacs package see Quickstart Package Guide
 719      (http://www.xemacs.org/Documentation/packageGuide.html).
 720
 721
 722 1.9 Microsoft Windows installation
 723 ==================================
 724
 725 For Microsoft Windows installation, please follow the next steps: (see
 726 separate instructions above for UNIX *Note Unix installation::.
 727
 728   1. cd to a directory where you keep emacs lisp files, or create a new
 729      directory (for example, `c:\emacs\') to hold the distribution.
 730      This directory will be referred to below as "the ESS distribution
 731      directory".  It will contain, at the end, either the tar file
 732      `ess-VERSION.tar.gz' or the zip file `ess-VERSION.zip', and a
 733      directory for the ESS source, which will be termed "the
 734      ESS-VERSION source directory".
 735
 736   2. Retrieve the compressed tar file `ess-VERSION.tar.gz' or the
 737      zipped file `ess-VERSION.zip' from one of the FTP or WWW archive
 738      sites via FTP (or HTTP).  Be aware that http browsers on Windows
 739      frequently change the "." and "-" characters in filenames to other
 740      punctuation.  Please change the names back to their original form.
 741
 742   3. Copy `ess-VERSION.tar.gz' to the location where you want the
 743      ess-VERSION directory, for example to
 744      `c:\emacs\ess-VERSION.tar.gz', and cd there.  For example,
 745
 746           cd c:\emacs
 747
 748      Extract the files from the distribution, which will unpack into a
 749      subdirectory, `ess-VERSION'.
 750           gunzip ess-VERSION.tar.gz
 751           tar xvf ess-VERSION.tar
 752           (or: `gunzip < ess-VERSION.tar.gz | tar xvf -' ).
 753           (or: from the zip file: `unzip ess-VERSION.zip')
 754
 755      The `tar' command will extract files into the current directory.
 756
 757      Do not create `ess-VERSION' yourself, or you will get an extra
 758      level of depth to your directory structure.
 759
 760   4. Windows users will usually be able to use the `lisp/ess-site.el'
 761      as distributed.  Only rarely will changes be needed.
 762
 763   5. Windows users will need to make sure that the directories for the
 764      software they will be using is in the PATH environment variable.
 765      On Windows 9x, add lines similar to the following to your
 766      `c:\autoexec.bat' file:
 767           path=%PATH%;c:\progra~1\spls2000\cmd
 768      On Windows NT/2000/XP, add the directories to the PATH using the
 769      `My Computer/Control Panel/System/Advanced/Environment Variables'
 770      menu.  Note that the directory containing the program is added to
 771      the PATH, not the program itself.  One such line is needed for
 772      each software program.  Be sure to use the abbreviation `progra~1'
 773      and not the long version with embedded blanks.  Use backslashes
 774      "\".
 775
 776   6. Add the line
 777           (load "/PATH/ess-site")
 778      to your .emacs (or _emacs) file (or default.el or site-init.el, for
 779      a site-wide installation).  Replace `/PATH' above with the value
 780      of ess-lisp-directory as defined in `ess-site.el'.  Use
 781      forwardslashes `/'.  (GNU Emacs uses the filename `%HOME%/.emacs'
 782      and XEmacs uses the filename `%HOME%/.xemacs/init.el' for the
 783      initialization file.)
 784
 785   7. To edit statistical programs, load the files with the requisite
 786      extensions  (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS,
 787      ".r" or ".R" for R, and ".lsp"   for XLispStat).
 788
 789   8. To run statistical processes under emacs:
 790
 791      To start the S-PLUS [67].x GUI from ESS under emacs:
 792           M-x S
 793           (or `M-x S+6').
 794      You will then be asked for a pathname ("S starting data
 795      directory?"), from which to start the process.  The prompt will
 796      propose your current directory as the default.  ESS will start the
 797      S-PLUS GUI.  There will be slight delay during which emacs is
 798      temporarily frozen.  ESS will arrange for communication with the
 799      S-PLUS GUI using the DDE protocol.  Send lines or regions from the
 800      emacs buffer containing your S program (for example, `myfile.s')
 801      to the S-PLUS Commands Window with the `C-c C-n' or `C-c C-r' keys.
 802      (If you are still using S-PLUS 4.x or 2000, then use `M-x S+4'.)
 803
 804      To start an S-PLUS [67].x session inside an emacs buffer--and
 805      without the S-PLUS GUI:
 806           M-x Sqpe
 807           (or `M-x Sqpe+6').
 808      You will then be asked for a pathname ("S starting data
 809      directory?"), from which to start the process.  The prompt will
 810      propose your current directory as the default.  You get Unix-like
 811      behavior, in particular the entire transcript is available for
 812      emacs-style search commands.  Send lines or regions from the emacs
 813      buffer containing your S program (for example, `myfile.s') to the
 814      *S+6* buffer with the `C-c C-n' or `C-c C-r' keys.  Interactive
 815      graphics are available with Sqpe by using the java library
 816      supplied with S-PLUS 6.1 and newer releases.  Enter the commands:
 817           library(winjava)
 818           java.graph()
 819      Graphs can be saved from the `java.graph' device in several
 820      formats, but not PostScript.   If you need a PostScript file you
 821      will need to open a separate `postscript' device.  (If you are
 822      still using S-PLUS 4.x or 2000, then use `M-x Sqpe+4'.)
 823
 824      To connect to an already running S-PLUS GUI (started, for example,
 825      from the S-PLUS icon):
 826           M-x S+6-existing
 827      You will then be asked for a pathname ("S starting data
 828      directory?"), from which to start the process.  The prompt will
 829      propose your current directory as the default.  ESS will arrange
 830      for communication with the already running S-PLUS GUI using the
 831      DDE protocol.  Send lines or regions from the emacs buffer
 832      containing your S program (for example, `myfile.s') to the S-PLUS
 833      Commands Window with the `C-c C-n' or `C-c C-r' keys.  (If you are
 834      still using S-PLUS 4.x or 2000, then use `M-x S+4-existing'.)
 835
 836      If you wish to run R, you can start it with:
 837           M-x R
 838
 839      XLispStat can not currently be run with
 840           M-x XLS
 841      Hopefully, this will change.  However, you can still edit with
 842      emacs, and cut and paste the results into the XLispStat *Listener*
 843      Window under Microsoft Windows.
 844
 845   9. That's it!
 846
 847
 848 1.10 Reporting Bugs
 849 ===================
 850
 851 Please send bug reports, suggestions etc. to
 852
 853    <ESS-bugs@stat.math.ethz.ch>
 854
 855    The easiest way to do this is within Emacs by typing
 856
 857    `M-x ess-submit-bug-report'
 858
 859    This also gives the maintainers valuable information about your
 860 installation which may help us to identify or even fix the bug.
 861
 862    If Emacs reports an error, backtraces can help us debug the problem.
 863 Type "M-x set-variable RET debug-on-error RET t RET".  Then run the
 864 command that causes the error and you should see a *Backtrace* buffer
 865 containing debug information; send us that buffer.
 866
 867    Note that comments, suggestions, words of praise and large cash
 868 donations are also more than welcome.
 869
 870 1.11 Mailing Lists
 871 ==================
 872
 873 There is a mailing list for discussions and announcements relating to
 874 ESS.  Join the list by sending an e-mail with "subscribe ess-help" (or
 875 "help") in the body to <ess-help-request@stat.math.ethz.ch>;
 876 contributions to the list may be mailed to
 877 <ess-help@stat.math.ethz.ch>.  Rest assured, this is a fairly
 878 low-volume mailing list.
 879
 880    The purposes of the mailing list include
 881
 882    *  helping users of ESS to get along with it.
 883
 884    *  discussing aspects of using ESS on Emacs and XEmacs.
 885
 886    *  suggestions for improvements.
 887
 888    *  announcements of new releases of ESS.
 889
 890    *  posting small patches to ESS.
 891
 892 1.12 Authors
 893 ============
 894
 895    * A.J. Rossini (mailto:blindglobe@gmail.com)
 896
 897    * Richard M. Heiberger (mailto:rmh@temple.edu)
 898
 899    * Kurt Hornik (mailto:Kurt.Hornik@R-project.org)
 900
 901    * Martin Maechler (mailto:maechler@stat.math.ethz.ch)
 902
 903    * Rodney A. Sparapani (mailto:rsparapa@mcw.edu)
 904
 905    * Stephen Eglen (mailto:stephen@gnu.org)
 906