README

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