doc/help-s.texi

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