README

   1 General Information: README
   2 ***************************
   3
   4    This is the README file for the distribution of ESS version
   5
   6    5.2.1
   7
   8    The first release of the 5.2 series.  ESS is a GNU Emacs and XEmacs
   9 mode for interactive statistical programming and data analysis.
  10 Languages supported: the S family (S 3/4, S-PLUS 3/4/5/6, and R), SAS,
  11 XLispStat, Stata and BUGS.  Installation help can be found in sections
  12 for both Unix and Windows.  ESS grew out of the desire for bug fixes and
  13 extensions to S-mode and SAS-mode as well as a consistent union of their
  14 features in one package.
  15
  16    The current development team is led by A.J. (Tony) Rossini
  17 (<rossini@biostat.washington.edu>), who did the initial port to XEmacs
  18 and has been the primary coder.  Martin Maechler
  19 (<maechler@stat.math.ethz.ch>) and Kurt Hornik
  20 (<hornik@ci.tuwien.ac.at>) have assisted with S-PLUS, S4, R, and
  21 XLispStat.  Richard M. Heiberger (<rmh@temple.edu>) has assisted with
  22 S-PLUS and S4 development for Windows.  Richard and Rodney A. Sparapani
  23 (<rsparapa@mcw.edu>) have done much of the work implementing
  24 interactive SAS (iESS[SAS]) and batch SAS (ESS[SAS]) support.
  25
  26    We are grateful to the previous developers of S-mode (Doug Bates, Ed
  27 Kademan, Frank Ritter, David M. Smith), SAS-mode (Tom Cook) and
  28 Stata-mode (Thomas Lumley).
  29
  30 License
  31 =======
  32
  33    ESS is free software; you can redistribute it and/or modify it under
  34 the terms of the GNU General Public License as published by the Free
  35 Software Foundation; either version 2, or (at your option) any later
  36 version.
  37
  38    ESS is distributed in the hope that it will be useful, but WITHOUT
  39 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  40 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  41 in the file COPYING in the same directory as this file for more details.
  42
  43 New Features
  44 ============
  45
  46    Changes/New Features in 5.2.1:
  47    * ESS[S] (R and S-plus): now have tool-bar with entries to evaluate
  48      code in the inferior process or to switch there.  This code is
  49      experimental and likely to change as XEmacs/Emacs issues get
  50      resolved.
  51
  52    Changes/New Features in 5.2.0:
  53    * ESS[BUGS]:  new info documentation!  now supports interactive
  54      processing thanks to Aki Vehtari (mailto:Aki.Vehtari@hut.fi); new
  55      architecture-independent unix support as well as support for BUGS
  56      v. 0.5
  57
  58    * ESS[SAS]:  convert .log to .sas with ess-sas-transcript; info
  59      documentation improved; Local Variable bug fixes; SAS/IML
  60      statements/functions now highlighted; files edited remotely by
  61      ange-ftp/EFS/tramp are recognized and pressing SUBMIT opens a
  62      buffer on the remote host via the local variable
  63      ess-sas-shell-buffer-remote-init which defaults to "ssh"; changed
  64      the definition of the variable ess-sas-edit-keys-toggle to boolean
  65      rather than 0/1; added the function ess-electric-run-semicolon
  66      which automatically reverse indents lines containing only "run;";
  67      C-F1 creates MS RTF portrait from the current buffer; C-F2 creates
  68      MS RTF landscape from the current buffer; C-F9 opens a SAS DATASET
  69      with PROC INSIGHT rather than PROC FSVIEW; C-F10 kills all buffers
  70      associated with .sas program; "inferior" aliases for SAS batch:
  71      C-c C-r for submit region, C-c C-b for submit buffer, C-c C-x for
  72      goto .log; C-c C-y for goto .lst
  73
  74    * ESS[S]: Pressing underscore ("_") once inserts " <- " (as before);
  75      pressing underscore twice inserts a literal underscore.  To stop
  76      this smart behaviour, add "(ess-smart-underscore nil)" to your
  77      .emacs after ess-site has been loaded;
  78      ess-dump-filename-template-proto (new name!) now can be customized
  79      successfully (for S language dialects); Support for Imenu has been
  80      improved; set ess-imenu-use-S to non-nil to get an "Imenu-S" item
  81      on your menubar; ess-help: Now using nice underlines (instead of
  82      `nuke-* ^H_')
  83
  84    * ESS[R]:  After (require 'essa-r), M-x ess-r-var allows to load
  85      numbers from any Emacs buffer into an existing *R* process; M-x
  86      ess-rdired gives a "directory editor" of R objects; fixed
  87      ess-retr-lastvalue-command, i.e. .Last.value bug (thanks to David
  88      Brahm)
  89
  90    * ESS: Support for creating new window frames has been added to ESS.
  91      Inferior ESS processes can be created in dedicated frames by
  92      setting inferior-ess-own-frame to t.  ESS help buffers can also
  93      open in new frames; see the documentation for ess-help-own-frame
  94      for details.  (Thanks to Kevin Rodgers for contributing code.)
  95
  96    Changes/New Features in 5.1.24:
  97    * The version number is now correct even inside ESS/Emacs
  98
  99    Changes/New Features in 5.1.23:
 100    * Minor more Makefile clean up.
 101
 102    Changes/New Features in 5.1.22:
 103    * Besides info documentation, PDF and HTML documentation are also
 104      provided (instead of built using "make") and available on the web
 105      as well; see ESS web page
 106      (http://software.biostat.washington.edu/ess/doc) and StatLib
 107      (http://lib.stat.cmu.edu/general/ESS/doc)
 108
 109    * Now that info documentation is available, the README.* files are
 110      no longer supported.  However, they are still distributed for what
 111      it's worth.
 112
 113    * ESS is now an XEmacs package!  See XEmacs Installation HOWTO
 114      (http://www.xemacs.org/Install/index.html) for details
 115      (specifically, items 10-15).
 116
 117    * ESS[SAS]: more user-friendly enhancements for remote SAS batch
 118      jobs with Kermit file transfers (LOG and OUTPUT function key
 119      features now supported).  Multiple shells now supported so you can
 120      run SAS on different computers from different buffers by setting
 121      the buffer-local variable ess-sas-shell-buffer to unique buffer
 122      names.
 123
 124    * Major re-vamping of Makefile/Makeconf.
 125
 126    Changes/New Features in 5.1.21:
 127    * ESS[SAS]: info documentation now available!, see ESS->Help for
 128      SAS; F12 opens GSASFILE nearest point for viewing either within
 129      emacs, when available, or via an external viewer; more syntax
 130      highlighting keywords; more enhancements for remote SAS batch jobs
 131      with Kermit; new framework for remote SAS interactive jobs, see
 132      ess-remote
 133
 134    * ESS[S]: info documentation now available!, see ESS->Help for the S
 135      family
 136
 137    * Makefile: tag now independent of rel; info files made by
 138      doc/Makefile and installed in new info sub-directory
 139
 140    Changes/New Features in 5.1.20:
 141    * New `options()$STERM' in the S dialects (S, S-Plus, R).  The S
 142      program can determine the environment in which it is currently
 143      running.  ESS sets the option to `iESS' or `ddeESS' when it starts
 144      an S language process.  We recommend other specific values for S
 145      language processes that ESS does not start.
 146
 147    * New `ess-mouse-me' function, assigned to S-mouse-3 by default.
 148      User may click on a word or region and then choose from the menu
 149      to display the item, or a summary, or a plot, etc.  This feature
 150      is still under development.
 151
 152    * GNU Emacs 21.1 is now supported (fixed for S dialects, SAS & BUGS),
 153      (some from Stephen Eglen).
 154
 155    * XEmacs 21.x is now supported (fixed w32-using-nt bug)
 156
 157    * XEmacs on Win (NT) is better supported.
 158
 159    * Workaround for bug in Sqpe+6 (S-PLUS 6 for Win).
 160
 161    * should now work even when imenu is not available (for old
 162      Xemacsen).
 163
 164    * ESS[SAS]: XEmacs-Imenu fix; C-TAB is globalized along with your
 165      function-key definitions, if specified; you can specify your SAS
 166      library definitions outside of autoexec.sas for ess-sas-data-view
 167      with SAS code placed in the variable ess-sas-data-view-libname,
 168      also the dataset name is defaulted to the nearest permanent dataset
 169      to point; Speedbar support now works for permanent datasets, please
 170      ignore first./last.; new font-locking is now the default with more
 171      improvements for font-locking PROCs, macro statements, * ; and %* ;
 172      comments; you can toggle sas-log-mode with F10 which will font-lock
 173      your .log (if it isn't too big); submit remote .sas files accessed
 174      with ange-ftp, EFS or Tramp (Kermit is experimental) by setting
 175      ess-sas-submit-method to 'sh; ess-sas-submit-command and
 176      ess-sas-submit-command-options are buffer-local so you can have
 177      local file variable sections at the end of your .sas files to
 178      request different executables or specify special options and the
 179      local file variables are re-read at submit instead of only at file
 180      open so that if you make a change it is picked up immediately;
 181
 182    * ESS[BUGS]: font-lock with `in' fixed.
 183
 184    * for STATA: font-lock bug fixed.
 185
 186    * for Rd mode: C-c C-v and `switch-process' in menu.  further, C-c
 187      C-f prefix (Rd-font) for inserting or surrounding a word by things
 188      such as \code{.}, \code{\link{.}}, \emph{.} etc.
 189
 190    * new functions (ess-directory-function) and (ess-narrow-to-defun)
 191      ess-directory <-> default-directory logic (Jeff Mincy).
 192
 193    * Re-organized Makefile and fixed a few bugs.
 194
 195    Changes/New Features in 5.1.19:
 196    * S+6 now supported (Tony Rossini (Unix) and Rich Heiberger
 197      (Windows))
 198
 199    * New BUGS support through ESS[BUGS] mode (Rodney Sparapani)
 200      Templates assist you in writing .bug and .cmd code (.cmd and .log
 201      are replaced by .bmd and .bog to avoid emacs extension collisions).
 202      Substitution" parameters facilitate "automagic" generation of
 203      data...in" and "init...in" filenames, "const N=" from your data
 204      file and "monitor()/stats()" commands.  Activated by pressing F12.
 205
 206    * Fixes for `ess-smart-underscore' SAS breakage (Rich Heiberger)
 207
 208    * You can change between PC and Unix, local and global SAS
 209      function-key definitions interactively (Rich Heiberger)
 210
 211    * C-Submit a highlighted region to SAS batch (Rodney Sparapani)
 212
 213    * New and improved SAS syntax highlighting (Rodney Sparapani) To get
 214      the new functionality, set ess-sas-run-make-regexp to nil.  Also
 215      available in .log files via F10.
 216
 217    * Open a permanent SAS dataset for viewing via F9 (Rodney Sparapani)
 218      You must have the library defined in autoexec.sas for it to work.
 219
 220    * User-friendly defaults for `sas-program',
 221      `ess-sas-batch-pre-command' and `ess-sas-batch-post-command' as
 222      well Customize support for these and other ESS[SAS] variables
 223      (Rodney Sparapani)
 224
 225    * `ess-sas-suffix-2' now defaults to .dat via F11 (Rodney Sparapani)
 226
 227    * Emacs/XEmacs, Unix/Windows issues collectively handled in
 228      ess-emcs.el
 229
 230    * defadvice solves problem of missing *ESS* (thanks to Jeff Mincy)
 231
 232    * Improved manual a bit by including things that were only in
 233      `README'.
 234
 235    Changes/New Features in 5.1.18:
 236    * New `ess-smart-underscore' function, now assigned to "_" by
 237      default.  Inserts `ess-S-assign' (customizable " <- "), unless
 238      inside string and comments where plain "_" is used instead. (MM)
 239
 240    * Fixes for longstanding interactive SAS breakage (RMH)
 241
 242    Changes/New Features in 5.1.17:
 243    * Documentation for Windows Installation (Rich Heiberger)
 244
 245    * removal of ess-vars, finalization of customize support (in the
 246      sense that there is no more use of ess-vars, but that we need to
 247      fix ess-cust) (AJ Rossini)
 248
 249    * Many small (and large) fixes/contributions (MMaechler)
 250
 251    * addition of the "S-equal" variable and provide M-x ess-add-MM-keys
 252      a way to remap "_" to `ess-S-assign', typically " <- ", but
 253      customizable. (MMaechler)
 254
 255    Changes/New Features in 5.1.16:
 256    * BUG FIXES
 257
 258    * Better SAS support
 259
 260    Changes/New Features in 5.1.15:
 261    * BUG FIXES
 262
 263    Changes/New Features in 5.1.14:
 264    * Yet more fixes to SAS mode, (Rich Heiberger and Rodney Sparapani)
 265
 266    * Customize support (for most Emacsen which support it) (AJRossini)
 267
 268    * ARC and ViSta support out of the box, and fixes for XLispStat
 269      (AJRossini)
 270
 271    Changes/New Features in 5.1.13:
 272    * Version numbering finally all depending on the ./VERSION file,
 273      thanks to Martin Maechler.
 274
 275    * Yet more fixes to SAS mode, thanks to Rich Heiberger.
 276
 277    Changes/New Features in 5.1.12:
 278    * Splus 5.1 stabilized, thanks to Martin Maechler, Bill Venables,
 279      Chuck Taylor, and others.
 280
 281    * More fixes to SAS mode, thanks to Rodney Sparapani and Rich
 282      Heiberger.
 283
 284    Changes/New Features in 5.1.11:
 285    * More fixes to Stata mode, thanks to Brendan Halpin
 286      (mailto:brendan@essex.ac.uk).
 287
 288    * fixed bugs in ESS-elsewhere, thanks to many testers
 289
 290    * README.SPLUS4WIN has DETAILED instructions for S-PLUS 2000, thanks
 291      to David Brahm (mailto:brahm@alum.mit.edu).
 292
 293    * Fixes to SAS mode, thanks to Rodney Sparapani
 294
 295    Changes/New Features in 5.1.10:
 296    * More fixes to Stata mode
 297
 298    * primitive generic version of ESS-elsewhere
 299
 300    * Small fixes to SAS/Stata.
 301
 302    Changes/New Features in 5.1.9:
 303    * Stata mode works
 304
 305    * Literate Data Analysis using Noweb works
 306
 307    Changes/New Features in 5.1.8:
 308    * Bug fixes
 309
 310    * R documentation mode defaults changed
 311
 312    Changes/New Features in 5.1.2:
 313    * able to use inferior iESS mode to communicate directly with a
 314      running S-Plus 4.x process using the Microsoft DDE protocol.  We
 315      use the familiar (from Unix ESS) C-c C-n and related key sequences
 316      to send lines from the S-mode file to the inferior S process.  We
 317      continue to edit S input files in ESS[S] mode and transcripts of
 318      previous S sessions in ESS Transcript mode.  All three modes know
 319      the S language, syntax, and indentation patterns and provide the
 320      syntactic highlighting that eases the programming tasks.
 321
 322 Current Features
 323 ================
 324
 325    * Languages Supported:
 326         * S family (S 3/4, S-PLUS 3.x/4.x/5.x/6.x, and R)
 327
 328         * SAS
 329
 330         * BUGS
 331
 332         * Stata
 333
 334         * XLispStat including Arc and ViSta
 335
 336    * Editing source code (S family, SAS, BUGS, XLispStat)
 337         * Syntactic indentation and highlighting of source code
 338
 339         * Partial evaluation of code
 340
 341         * Loading and error-checking of code
 342
 343         * Source code revision maintenance
 344
 345         * Batch execution (SAS, BUGS)
 346
 347         * Use of imenu to provide links to appropriate functions
 348
 349    * Interacting with the process (S family, SAS, XLispStat)
 350         * Command-line editing
 351
 352         * Searchable Command history
 353
 354         * Command-line completion of S family object names and file
 355           names
 356
 357         * Quick access to object lists and search lists
 358
 359         * Transcript recording
 360
 361         * Interface to the help system
 362
 363    * Transcript manipulation (S family, XLispStat)
 364         * Recording and saving transcript files
 365
 366         * Manipulating and editing saved transcripts
 367
 368         * Re-evaluating commands from transcript files
 369
 370    * Help File Editing (R)
 371         * Syntactic indentation and highlighting of source code.
 372
 373         * Sending Examples to running ESS process.
 374
 375         * Previewing
 376
 377 Stability
 378 =========
 379
 380    Versions 5.1.x are meant to be gamma-level releases.  While some bugs
 381 are fixed, others may have been introduced, especially with regards to
 382 new features.  See the file doc/TODO for details.  Bug reports are
 383 solicited; see the Bugs Section below.  Patches or suggested coding
 384 fixes with bug reports are much appreciated!
 385
 386 Requirements
 387 ============
 388
 389    ESS has been tested with
 390
 391    * S-PLUS 3.3, 3.4, 4.5, 5.0, 5.1, 6.0, 6.1, 2000
 392
 393    * R >=0.49
 394
 395    * S4
 396
 397    * SAS >=6.12
 398
 399    * BUGS 0.5, 0.603
 400
 401    * Stata >=6.0
 402
 403    * XLispStat >=3.50
 404
 405    on the following platforms
 406
 407    * Linux (all)
 408
 409    * Solaris/SunOS (all)
 410
 411    * Microsoft Windows 95/98/NT/2000 (SPLUS 4.5/2000, R, SAS and BUGS)
 412
 413    * Apple Mac OS (SAS for OS 9 and X11 R for OS X)
 414
 415    with the following versions of emacs
 416
 417    * GNU Emacs 20.3, 20.4, 20.5, 20.6, 20.7, 21.1, 21.3
 418
 419    * XEmacs 21.0, 21.1.13-14, 21.4.0-8, 21.4.9-13/21.5.17(1), 21.4.14-15
 420
 421    * GNU Emacs <20.3 and XEmacs <21.0(2)
 422
 423    ---------- Footnotes ----------
 424
 425    (1) requires the files.el patch to revert-buffer for the Local
 426 Variables updating problem
 427
 428    (2) These releases of emacs are no longer supported, so an upgrade
 429 is recommended if you plan to use ESS.  If you have GNU Emacs 19.29,
 430 see *Note Unix installation::.  Also, note that the `custom' library
 431 bundled with Emacs 19.34 is too _old_, its API is incompatible with the
 432 `new custom' bundled with recent Emacsen.  The `new custom' for Emacs
 433 19.34 is available for download here
 434 (ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz).
 435
 436 Getting the Latest Version
 437 ==========================
 438
 439    The latest version of ESS is always available on the web at: ESS web
 440 page (http://www.analytics.washington.edu/downloads/ess/) or StatLib
 441 (http://lib.stat.cmu.edu/general/ESS/)
 442
 443    There no longer is an anonymous CVS repository for ESS, due to lack
 444 of interest, little demand, and problems with security.
 445
 446 Installation (from tar file)
 447 ============================
 448
 449    We now discuss installation, which might happen under Unix or
 450 Microsoft Windows.  First, we discuss Unix installation.  *Note Unix
 451 installation::.
 452
 453    For Microsoft Windows Installation please skip to the *Note
 454 Microsoft Windows installation::.
 455
 456 Unix installation
 457 =================
 458
 459   1. cd to a directory where you want to install ESS, creating it if
 460      necessary.  This directory will be referred to below as ESSDIR.
 461
 462   2. Retrieve the latest version from gzipped tar file
 463      (http://www.analytics.washington.edu/downloads/ess/ess-VERSION.tar.gz)
 464      to ESSDIR.
 465
 466   3. Decompress/unarchive the files from the disribution.
 467           gunzip ess-VERSION.tar.gz
 468           tar xvf ess-VERSION.tar
 469
 470           (or: `gunzip < ess-VERSION.tar.gz | tar xvf -' ).
 471           (or using GNU tar:  `tar zxvf ess-VERSION.tar.gz').
 472
 473      The `tar' command will create the subdirectory ess-VERSION and
 474      unarchive the files there.
 475
 476      If you are using GNU Emacs 19.29, decompress/unarchive
 477      `ESSDIR/ess-VERSION/lisp/19.29.tar.gz', read
 478      `ESSDIR/ess-VERSION/lisp/19.29/README', follow the instructions
 479      and you might be able to get ESS to work.  _Please note that GNU
 480      Emacs 19.29 is no longer supported_.  For a list of supported
 481      versions of emacs, see *Note Requirements::.
 482
 483   4. Edit the file `ESSDIR/ess-VERSION/lisp/ess-site.el' as explained
 484      in the comments section of that file.
 485
 486   5.  Add the line
 487           (load "ESSDIR/ess-VERSION/lisp/ess-site")
 488      to your user or system installation file (GNU Emacs uses
 489      `$HOME/.emacs' and XEmacs uses `$HOME/.xemacs/init.el' for the
 490      user initialization file.  GNU Emacs uses default.el or
 491      site-init.el and XEmacs uses site-start.el for the system
 492      installation file).
 493
 494      Alternatively, if ess-site.el is in your current Lisp path, you
 495      can do:
 496           (require 'ess-site)
 497      to configure emacs for ESS.
 498
 499   6. That's it!  To edit statistical programs, load the files with the
 500      requiste extensions  (".sas" for SAS, ".S" for S-PLUS, ".R" for R,
 501      and ".lsp" for XLispStat).
 502
 503   7. (OPTIONAL) If you are running S-PLUS or R, you might consider
 504      installing the database files.  From within emacs, `C-x d' to the
 505      directory containing ESS.  Now:
 506           M-x S+6
 507      to get S running.  Once you see the SPLUS prompt, do:
 508           M-x ess-create-object-name-db
 509      (this will create the file `ess-s+6-namedb.el'; if it isn't in the
 510      ESS directory, move it there).
 511
 512      Then, completions will be autoloaded and will not be regenerated
 513      for every session.
 514
 515      For R, do the same, using
 516           M-x R
 517      and then `M-x ess-create-object-name-db' creating
 518      `ess-r-namedb.el'; if it isn't in the ESS directory, move it
 519      there).
 520
 521   8. (OPTIONAL) READ THIS ITEM THOROUGHLY BEFORE STARTING:
 522
 523      If you want to place the compiled files in other locations edit
 524      the LISPDIR and INFODIR entries in `Makeconf' in the
 525      ESSDIR/ess-VERSION directory (if you are using XEmacs, then you
 526      also need to edit the EMACS entry as follows:  EMACS=xemacs).
 527
 528      You can compile those files by:
 529           make all
 530
 531      When that completes successfully, install the compiled files:
 532           make install
 533
 534      This will install the compiled info files and lisp files.  If you
 535      are an XEmacs user, then you should be done.  If not, then you may
 536      have to edit/create the file `dir' that is found in the directory
 537      specified by `INFODIR': see the sample `dir' in
 538      ESSDIR/ess-VERSION/doc.  If `dir' does not exist in `INFODIR',
 539      then the sample `dir' will be installed.
 540
 541      _Note 1:_ It is assumed that GNU make will be used; otherwise,
 542      edit the ESSVERSION and ESSVERSIONTAG entries in `Makeconf'
 543      appropriately, e.g.: ESSVERSION=5.2.0 and ESSVERSIONTAG=ESS-5-2-0
 544
 545      _Note 2:_  ESS can be installed for XEmacs as an XEmacs package
 546      much more easily than what has been described anywhere above.
 547      However, the latest ESS version will not be available at the same
 548      time as an XEmacs package; generally, it can take weeks or months
 549      to appear in the latter format.  For more information on
 550      installing ESS as an XEmacs package see QuickStart
 551      (http://www.xemacs.org/Documentation/packageGuide.html).
 552
 553
 554 Microsoft Windows installation
 555 ==============================
 556
 557    For Microsoft Windows installation, please follow the next steps:
 558 (see separate instructions above for UNIX *Note Unix installation::.
 559
 560   1. cd to a directory where you keep emacs lisp files, or create a new
 561      directory (for example, `c:\emacs\') to hold the distribution.
 562      This directory will be referred to below as "the ESS distribution
 563      directory".  It will contain, at the end, either the tar file
 564      `ess-VERSION.tar.gz' or the zip file `ess-VERSION.zip', and a
 565      directory for the ESS source, which will be termed "the
 566      ESS-VERSION source directory".
 567
 568   2. Retrieve the compressed tar file `ess-VERSION.tar.gz' or the
 569      zipped file `ess-VERSION.zip' from one of the FTP or WWW archive
 570      sites via FTP (or HTTP).  Be aware that http browsers on Windows
 571      frequently change the "." and "-" characters in filenames to other
 572      punctuation.  Please change the names back to their original form.
 573
 574   3. Copy `ess-VERSION.tar.gz' to the location where you want the
 575      ess-VERSION directory, for example to
 576      `c:\emacs\ess-VERSION.tar.gz', and cd there.  For example,
 577
 578           cd c:\emacs
 579
 580      Extract the files from the distribution, which will unpack into a
 581      subdirectory, `ess-VERSION'.
 582           gunzip ess-VERSION.tar.gz
 583           tar xvf ess-VERSION.tar
 584           (or: `gunzip < ess-VERSION.tar.gz | tar xvf -' ).
 585           (or: from the zip file: `unzip ess-VERSION.zip')
 586
 587      The `tar' command will extract files into the current directory.
 588
 589      Do not create `ess-VERSION' yourself, or you will get an extra
 590      level of depth to your directory structure.
 591
 592   4. Windows users will usually be able to use the `lisp/ess-site.el'
 593      as distributed.  Only rarely will changes be needed.
 594
 595   5. Windows users will need to make sure that the directories for the
 596      software they will be using is in the PATH environment variable.
 597      On Windows 9x, add lines similar to the following to your
 598      `c:\autoexec.bat' file:
 599           path=%PATH%;c:\progra~1\spls2000\cmd
 600      On Windows NT/2000, add the directories to the PATH using the
 601      MyComputer menu.  Note that the directory containing the program is
 602      added to the PATH, not the program itself.  One such line is needed
 603      for each software program.  Be sure to use the abbreviation
 604      `progra~1' and not the long version with embedded blanks.  Use
 605      backslashes "\".
 606
 607   6. Add the line
 608           (load "/PATH/ess-site")
 609      to your .emacs (or _emacs) file (or default.el or site-init.el, for
 610      a site-wide installation).  Replace `/PATH' above with the value
 611      of ess-lisp-directory as defined in `ess-site.el'.  Use
 612      forwardslashes `/'.  (GNU Emacs uses the filename `%HOME%/.emacs'
 613      and XEmacs uses the filename `%HOME%/.xemacs/init.el' for the
 614      initialization file.)
 615
 616   7. To edit statistical programs, load the files with the requisite
 617      extensions  (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS,
 618      ".r" or ".R" for R, and ".lsp"   for XLispStat).
 619
 620   8. To run statistical processes under emacs:
 621
 622      Run S-PLUS 6.x or 2000 with:
 623           M-x S+6
 624           (or `M-x S').
 625      You will then be asked for a pathname ("S starting data
 626      directory?"), from which to start the process.  The prompt will
 627      propose your current directory as the default.  Similarly for
 628      S-PLUS 6.x.  Send lines or regions from the emacs buffer
 629      containing your S program (for example, `myfile.s') to the S-Plus
 630      Commands Window with the `C-c C-n' or `C-c C-r' keys.
 631
 632      Run S-PLUS 6.x or 2000 inside an emacs buffer
 633           M-x Sqpe+6
 634      You will then be asked for a pathname ("S starting data
 635      directory?"), from which to start the process.  The prompt will
 636      propose your current directory as the default.  Similarly for
 637      S-PLUS 6.x.  Send lines or regions from the emacs buffer
 638      containing your S program (for example, `myfile.s') to the *S+6*
 639      buffer with the `C-c C-n' or `C-c C-r' keys.  You do not have
 640      access to interactive graphics in this mode.  You get Unix-like
 641      behavior, in particular the entire transcript is available for
 642      emacs-style search commands.
 643
 644      If you wish to run R, you can start it with:
 645           M-x R
 646
 647      XLispStat can not currently be run with
 648           M-x XLS
 649      Hopefully, this will change.  However, you can still edit with
 650      emacs, and cut and paste the results into the XLispStat *Listener*
 651      Window under Microsoft Windows.
 652
 653      SAS for Windows uses the batch access with function keys that is
 654      described in `doc/README.SAS'.  The user can also edit SAS files
 655      in an `ESS[SAS]' buffer and than manually copy and paste them into
 656      an Editor window in the SAS Display Manager.
 657
 658      For Windows, inferior SAS in an `iESS[SAS]' buffer does not work
 659      on the local machine.  It does work over a network connection to
 660      SAS running on a remote Unix computer.
 661
 662      Reason:  we use ddeclient to interface with programs and SAS
 663      doesn't provide the corresponding ddeserver capability.
 664
 665   9. (OPTIONAL) If you are running Sqpe or R, you might consider
 666      installing the database files.  From within emacs, `C-x d' to the
 667      directory containing ESS.  Now:
 668           M-x Sqpe+6
 669      to get S running.  Once you see the SPLUS prompt, do:
 670           M-x ess-create-object-name-db
 671      (this will create the file `ess-s+6-namedb.el'; if it isn't in the
 672      ESS directory, move it there).
 673
 674      Then, completions will be autoloaded and will not be regenerated
 675      for every session.
 676
 677      For R, do the same, using
 678           M-x R
 679      and then `M-x ess-create-object-name-db' creating
 680      `ess-r-namedb.el'; if it isn't in the ESS directory, move it
 681      there).
 682
 683  10. That's it!
 684
 685
 686 Requirements
 687 ============
 688
 689    ESS has been tested with
 690
 691    * S-PLUS 3.3, 3.4, 4.5, 5.0, 5.1, 6.0, 6.1, 2000
 692
 693    * R >=0.49
 694
 695    * S4
 696
 697    * SAS >=6.12
 698
 699    * BUGS 0.5, 0.603
 700
 701    * Stata >=6.0
 702
 703    * XLispStat >=3.50
 704
 705    on the following platforms
 706
 707    * Linux (all)
 708
 709    * Solaris/SunOS (all)
 710
 711    * Microsoft Windows 95/98/NT/2000 (SPLUS 4.5/2000, R, SAS and BUGS)
 712
 713    * Apple Mac OS (SAS for OS 9 and X11 R for OS X)
 714
 715    with the following versions of emacs
 716
 717    * GNU Emacs 20.3, 20.4, 20.5, 20.6, 20.7, 21.1, 21.3
 718
 719    * XEmacs 21.0, 21.1.13-14, 21.4.0-8, 21.4.9-13/21.5.17(1), 21.4.14-15
 720
 721    * GNU Emacs <20.3 and XEmacs <21.0(2)
 722
 723    ---------- Footnotes ----------
 724
 725    (1) requires the files.el patch to revert-buffer for the Local
 726 Variables updating problem
 727
 728    (2) These releases of emacs are no longer supported, so an upgrade
 729 is recommended if you plan to use ESS.  If you have GNU Emacs 19.29,
 730 see *Note Unix installation::.  Also, note that the `custom' library
 731 bundled with Emacs 19.34 is too _old_, its API is incompatible with the
 732 `new custom' bundled with recent Emacsen.  The `new custom' for Emacs
 733 19.34 is available for download here
 734 (ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz).
 735
 736 Reporting Bugs
 737 ==============
 738
 739    Please send bug reports, suggestions etc. to
 740
 741    <ESS-bugs@stat.math.ethz.ch>
 742
 743    The easiest way to do this is within Emacs by typing
 744
 745    `M-x ess-submit-bug-report'
 746
 747    This also gives the maintainers valuable information about your
 748 installation which may help us to identify or even fix the bug.
 749
 750    If Emacs reports an error, backtraces can help us debug the problem.
 751 Type "M-x set-variable RET debug-on-error RET t RET".  Then run the
 752 command that causes the error and you should see a *Backtrace* buffer
 753 containing debug information; send us that buffer.
 754
 755    Note that comments, suggestions, words of praise and large cash
 756 donations are also more than welcome.
 757
 758 Mailing Lists
 759 =============
 760
 761    There is a mailing list for discussions and announcements relating to
 762 ESS.  Join the list by sending an e-mail with "subscribe ess-help" (or
 763 "help") in the body to <ess-help-request@stat.math.ethz.ch>;
 764 contributions to the list may be mailed to
 765 <ess-help@stat.math.ethz.ch>.  Rest assured, this is a fairly
 766 low-volume mailing list.
 767
 768    The purposes of the mailing list include
 769
 770    *  helping users of ESS to get along with it.
 771
 772    *  discussing aspects of using ESS on Emacs and XEmacs.
 773
 774    *  suggestions for improvements.
 775
 776    *  announcements of new releases of ESS.
 777
 778    *  posting small patches to ESS.
 779
 780 Authors
 781 =======
 782
 783    * A.J. Rossini (mailto:rossini@u.washington.edu)
 784
 785    * Richard M. Heiberger (mailto:rmh@temple.edu)
 786
 787    * Kurt Hornik (mailto:hornik@ci.tuwien.ac.at)
 788
 789    * Martin Maechler (mailto:maechler@stat.math.ethz.ch)
 790
 791    * Rodney A. Sparapani (mailto:rsparapa@mcw.edu)
 792
 793    * Stephen Eglen (mailto:stephen@gnu.org)
 794