README

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