README

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