doc/README.S

   1 -*- text -*-
   2
   3 ($Revision: 5.2 $)
   4
   5 ESS: Using The S family of statistical languages
   6 ================================================
   7
   8 ESS (originally S-mode) was initially designed for use with S and
   9 S-PLUS(tm); hence, this family of statistical languages currently has
  10 the most support.  We denote by _S_, any of the currently available
  11 members of the family, including S 3.x, S 4.x, S-PLUS 3.x, S-PLUS 4.x,
  12 S-PLUS 5.x, and R.  In addition, we denote by _Emacs_, one of the GNU
  13 family of editors, either Emacs (as developed and maintained by the
  14 Free Software Foundation) or XEmacs (which is a derivative work).
  15
  16 The following is covered in this document:
  17 - general Emacs features.
  18 - Editing files.
  19 - running an S process as an inferior process to Emacs
  20 - using transcripts.
  21 - Scenarios for use (possibilities, based on actual usage)
  22 - Philosophies
  23
  24 New in 5.1.2 and later: use under Microsoft Windows OS's with NTEmacs.
  25 See the file README.SPLUS4WIN for more details.
  26
  27 Emacs: General features
  28 =======================
  29
  30 We assume that you are familiar with Emacs terminology and syntax:
  31 file, buffer, region, description of keys etc.  If not, please read
  32 the New Users guide (found in the info pages, "C-h i" (by pressing
  33 control h, i) or Tutorial, "C-h t").
  34
  35 To find the key-sequences for commands, view the keymap (C-h b) or
  36 view help for the current mode (C-h m).
  37
  38 ESS[S]: Editing Files
  39 =====================
  40
  41 ESS[S] is the mode for editing S language files.  This mode handles:
  42
  43 - proper indenting, generated by both [Tab] and [Return].
  44 - color and font choices based on syntax.
  45 - ability to send the contents of an entire buffer, a highlighted
  46   region, an S function, or a single line to an inferior S process, if
  47   one is currently running.
  48 - ability to switch between processes which would be the target of the
  49   buffer (for the above).
  50 - The ability to request help from an S process for variables and
  51   functions, and to have the results sent into a separate buffer.
  52 - completion of object names and file names.
  53
  54 ESS[S] mode should be automatically turned on when loading a file with
  55 the suffices found in ess-site (*.R, *.S, *.s, etc).  However, one
  56 will have to start up an inferior process to take advantage of the
  57 interactive features.
  58
  59
  60 iESS: Inferior ESS processes.
  61 =============================
  62
  63 iESS (inferior ESS) is the mode for interfacing with active
  64 statistical processes (programs).  This mode handles:
  65
  66 - proper indenting, generated by both [Tab] and [Return].
  67 - color and font highlighting based on syntax.
  68 - ability to resubmit the contents of a multi-line command
  69   to the executing process with a single keystroke [RET].
  70 - The ability to request help from the current process for variables
  71   and functions, and to have the results sent into a separate buffer.
  72 - completion of object names and file names.
  73 - interactive history mechanism
  74 - transcript recording and editing
  75
  76 To start up iESS mode, use:
  77    M-x S+3
  78    M-x S4
  79    M-x R
  80
  81 (for S-PLUS 3.x, S4, and R, respectively.  This assumes that you have
  82 access to each).  Usually the site will have defined one of these programs
  83 (by default S+3) to the simpler name:
  84
  85    M-x S
  86
  87 Note that R has some extremely useful command line arguments,
  88 -v and -n.   To enter these, call R using a "prefix argument", by
  89
  90    C-u M-x R
  91
  92 and when ESS prompts for "Starting Args ? ", enter (for example):
  93
  94    -v 10000 -n 5000
  95
  96 Then that R process will be started up using "R -v 10000 -n 5000".
  97
  98 New for ESS 5.1.2 (and later):  "S-elsewhere" command
  99
 100   The idea of "M-x S-elsewhere" is that we open a telnet (or rlogin)
 101   to another machine, call the buffer "*S-elsewhere*", and then run S
 102   on the other machine in that buffer.  We do that by defining "sh" as
 103   the inferior-S-elsewhere-program-name.  Emacs sets it up in a
 104   "*S-elsewhere*" iESS buffer.  The user does a telnet or login from
 105   that buffer to the other machine and then starts S on the other
 106   machine.  The usual C-c C-n commands from myfile.s on the local
 107   machine get sent through the buffer "*S-elsewhere*" to be executed
 108   by S on the other machine.
 109
 110
 111 ESS-trans: Handling and Reusing Transcripts
 112 ===========================================
 113
 114 - edit transcript
 115 - color and font highlighting based on syntax.
 116 - resubmit multi-line commands to an active process buffer
 117 - The ability to request help from an S process for variables and
 118   functions, and to have the results sent into a separate buffer.
 119 - ability to switch between processes which would be the target of the
 120   buffer (for the above).
 121
 122
 123
 124 ESS-help: assistance with viewing help
 125 ======================================
 126
 127 - move between help sections
 128 - send examples to S for evaluation
 129
 130
 131 Philosophies for using ESS
 132 ==========================
 133
 134 The first is preferred, and configured for.  The second one can be
 135 retrieved again, by changing emacs variables.
 136
 137 1: (preferred by the current group of developers):  The source code is
 138    real.  The objects are realizations of the source code.  Source
 139    for EVERY user modified object is placed in a particular directory
 140    or directories, for later editing and retrieval.
 141
 142 2: (older version): S objects are real.  Source code is a temporary
 143    realization of the objects.  Dumped buffers should not be saved.
 144    _We_strongly_discourage_this_approach_.  However, if you insist,
 145    add the following lines to your .emacs file:
 146
 147       (setq ess-keep-dump-files 'nil)
 148       (setq ess-delete-dump-files t)
 149       (setq ess-mode-silently-save nil)
 150
 151 The second saves a small amount of disk space.  The first allows for
 152 better portability as well as external version control for code.
 153
 154
 155 Scenarios for use
 156 =================
 157
 158 We present some basic suggestions for using ESS to interact with S.
 159 These are just a subset of approaches, many better approaches are
 160 possible.  Contributions of examples of how you work with ESS are
 161 appreciated (especially since it helps us determine priorities on
 162 future enhancements)! (comments as to what should be happening are
 163 prefixed by "##").
 164
 165 1:  ##    Data Analysis Example (source code is real)
 166     ## Load the file you want to work with
 167     C-x C-f myfile.s
 168
 169     ## Edit as appropriate, and then start up S-PLUS 3.x
 170     M-x S+3
 171
 172     ## A new buffer *S+3:1* will appear.  Splus will have been started
 173     ## in this buffer.  The buffer is in iESS [S+3:1] mode.
 174
 175     ## Split the screen and go back to the file editing buffer.
 176     C-x 2 C-x b myfile.s
 177
 178     ## Send regions, lines, or the entire file contents to S-PLUS.  For regions,
 179     ## highlight a region with keystrokes or mouse and then send with:
 180     C-c C-r
 181
 182     ## Re-edit myfile.s as necessary to correct any difficulties.  Add
 183     ## new commands here.  Send them to S by region with C-c C-r, or
 184     ## one line at a time with C-c C-n.
 185
 186     ## Save the revised myfile.s with C-x C-s.
 187
 188     ## Save the entire *S+3:1* interaction buffer with C-c C-s.  You
 189     ## will be prompted for a file name.  The recommended name is
 190     ## myfile.St.  With the *.St suffix, the file will come up in ESS
 191     ## Transcript mode the next time it is accessed from Emacs.
 192
 193
 194
 195 2:  ## Program revision example (source code is real)
 196
 197     ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
 198     M-x S+3
 199
 200     ## Load the file you want to work with
 201     C-x C-f myfile.s
 202
 203     ## edit program, functions, and code in myfile.s, and send revised
 204     ## functions to S when ready with
 205     C-c C-f
 206     ## or highlighted regions with
 207     C-c C-r
 208     ## or individual lines with
 209     C-c C-n
 210     ## or load the entire buffer with
 211     C-c C-l
 212
 213     ## save the revised myfile.s when you have finished
 214     C-c C-s
 215
 216
 217
 218 3:  ## Program revision example (S object is real)
 219
 220     ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
 221     M-x S+3
 222
 223     ## Dump an existing S object my.function into a buffer to work with
 224     C-c C-d my.function
 225     ## a new buffer named yourloginname.my.function.S will be created with
 226     ## an editable copy of the object.  The buffer is associated with the
 227     ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not
 228     ## exist after you log off.
 229
 230     ## enter program, functions, and code into work buffer, and send
 231     ## entire contents to S-PLUS when ready
 232     C-c C-b
 233
 234     ## Go to *S+3:1* buffer, which is the process buffer, and examine
 235     ## the results.
 236     C-c C-y
 237     ## The sequence C-c C-y is a shortcut for:  C-x b *S+3:1*
 238
 239     ## Return to the work buffer (may/may not be prefixed)
 240     C-x C-b yourloginname.my.function.S
 241     ## Fix the function that didn't work, and resubmit by placing the
 242     ## cursor somewhere in the function and
 243     C-c C-f
 244     ## Or you could've selected a region (using the mouse, or keyboard
 245     ## via setting point/mark) and
 246     C-c C-r
 247     ## Or you could step through, line by line, using
 248     C-c C-n
 249     ## Or just send a single line (without moving to the next) using
 250     C-c C-j
 251     ## To fix that error in syntax for the "rchisq" command, get help
 252     ## by
 253     C-c C-v rchisq
 254
 255
 256 4:    Data Analysis (S object is real)
 257     ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*)
 258     M-x S+3
 259
 260     ## Work in the process buffer.  When you find an object that needs
 261     ## to be changed (this could be a data frame, or a variable, or a
 262     ## function), dump it to a buffer:
 263     C-c C-d my.cool.function
 264
 265     ## Edit the function as appropriate, and dump back in to the
 266     ## process buffer
 267     C-c C-b
 268
 269     ## Return to the S-PLUS process buffer
 270     C-c C-y
 271     ## Continue working.
 272
 273     ## When you need help, use
 274     C-c C-v rchisq
 275     ## instead of entering:   help("rchisq")
 276
 277
 278
 279 Customization Examples and Solutions to Problems
 280 ================================================
 281
 282 1. Suppose that you are primarily an SPLUS 3.4 user, occasionally
 283    using S version 4, and sick and tired of the buffer-name *S+3*
 284    we've stuck you with.  Simply edit the "ess-dialect" alist entry in
 285    the essd-s+3.el and essd-s4.el files to be "S" instead of "S4" and
 286    "S+3".  This will insure that all the inferior process buffer names
 287    are "*S*".
 288
 289 2. Suppose that you WANT to have the first buffer name indexed by
 290    ":1", in the same manner as your S-PLUS processes 2,3,4, and 5 (for
 291    you heavy simulation people).  Then uncomment the line in ess-site
 292    (or add after your (require 'ess-site) or (load "ess-site") command
 293     in your .emacs file, the line:
 294
 295        (setq ess-plain-first-buffername nil)
 296    )
 297
 298 3. Fontlocking sometimes fails to behave nicely upon errors.  When
 299    Splus dumps, a mis-matched "  (double-quote) can result in the
 300    wrong font-lock face being used for the remainder of the buffer.
 301
 302    Solution: add a " at the end of the "Dumped..." statement, to
 303    revert the font-lock face back to normal.