ESS[SAS]: somebody forgot about the SUM statement (probably me)

[ess.git] / doc / help-s.texi

@node ESS(S)--Editing files, iESS(S)--Inferior ESS processes, , ESS for the S family
@comment  node-name,  next,  previous,  up -- don't use @ESS ..
@section ESS[S]--Editing files

@ESS{[S]} is the mode for editing S language files.  This mode handles:

@itemize @minus
@item
 proper indenting, generated by both [Tab] and [Return].
@item
 color and font choices based on syntax.
@item
 ability to send the contents of an entire buffer, a highlighted
  region, an S function, or a single line to an inferior S process, if
  one is currently running.
@item
 ability to switch between processes which would be the target of the
  buffer (for the above).
@item
 The ability to request help from an S process for variables and
  functions, and to have the results sent into a separate buffer.
@item
 completion of object names and file names.
@end itemize

@ESS{[S]} mode should be automatically turned on when loading a file with
the suffices found in ess-site (*.R, *.S, *.s, etc).  However, one
will have to start up an inferior process to take advantage of the
interactive features.

@node iESS(S)--Inferior ESS processes, ESS-help--assistance with viewing help, ESS(S)--Editing files, ESS for the S family
@comment  node-name,  next,  previous,  up
@section iESS[S]--Inferior ESS processes
iESS (inferior ESS) is the mode for interfacing with active
statistical processes (programs).  This mode handles:

@itemize @minus
@item
 proper indenting, generated by both [Tab] and [Return].
@item
 color and font highlighting based on syntax.
@item
 ability to resubmit the contents of a multi-line command
 to the executing process with a single keystroke [RET].
@item
 The ability to request help from the current process for variables
 and functions, and to have the results sent into a separate buffer.
@item
 completion of object names and file names.
@item
 interactive history mechanism.
@item
 transcript recording and editing.
@end itemize

To start up iESS mode, use:
@example
   M-x S+3
   M-x S4
   M-x S+5
   M-x S+6
   M-x R
@end example

(for S-PLUS 3.x, S4, S+5, S+6 or S+7, and R, respectively.  This assumes that
you have access to each).  Usually the site will have defined one of
these programs (by default S+6) to the simpler name:

   M-x S

In the (rare) case that you wish to pass command line arguments to the
starting S+6 process, set the variable @code{inferior-Splus-args}.

Note that R has some extremely useful command line arguments.  For
example, @code{--vanilla} will ensure R starts up without loading in any init
files.  To enter a command line argument, call R using a "prefix
argument", by

   C-u M-x R

and when ESS prompts for "Starting Args ? ", enter (for example):

   @code{--vanilla}

Then that R process will be started up using @code{R --vanilla}.  If you
wish to always call R with certain arguments, set the variable
@code{inferior-R-args} accordingly.

@comment Menubar access to other versions of R and Sqpe

If you have other versions of R or S-Plus available on the system, ESS
is also able to start those versions.  How this works depend on which OS
you are using:


R on Unix systems:
If you have "R-1.8.1" on
your `exec-path', it can be started using @kbd{M-x R-1.8.1}.  By
default, ESS will find versions of R beginning "R-1" or "R-2".  If your
versions of R are called other names, consider renaming them with a
symbolic link or change the variable @code{ess-r-versions}.  To see
which defuns have been created for starting different versions of R,
type @kbd{M-x R-} and then hit [Tab].  You will then see if any defuns
for particular versions of R have been created.  These other versions of
R can also be started from the "ESS->Start Process->Other" menu.

R on Windows systems:
If you have "rw1081" on
your `exec-path', it can be started using @kbd{M-x rw1081}.  By
default, ESS will find versions of R located in directories
parallel to the version of R in your @code{PATH}.  If your
versions of R are called other names, you will need to change the variable
@code{ess-rterm-versions}.  To see
which defuns have been created for starting different versions of R,
type @kbd{M-x rw} and then hit [Tab].  You will then see if any defuns
for particular versions of R have been created.  These other versions of
R can also be started from the "ESS->Start Process->Other" menu.

Once ESS has found these extra versions of R, it will then create a new
defun, called @kbd{M-x R-newest}, which will call the newest version of
R that it found.  (ESS examines the date in the first line of
information from @code{R --version} to determine which is newest.)

S on Unix systems: If you have "Splus7" on your `exec-path', it can be
started using @kbd{M-x Splus7}.  By default, ESS will find all
executables beginning "Splus" on your path.  If your versions of S are
called other names, consider renaming them with a symbolic link or
change the variable @code{ess-s-versions}.  To see which defuns have
been created for starting different versions of Splus, type @kbd{M-x
Splus} and then hit [Tab].  You will then see if any defuns for
particular versions of Splus have been created.  These other versions of
Splus can also be started from the "ESS->Start Process->Other" menu.

A second mechanim is also available for running other versions of Splus.
The variable @code{ess-s-versions-list} is a list of lists; each sublist
should be of the form: (DEFUN-NAME PATH ARGS).  DEFUN-NAME is the name
of the new emacs function you wish to create to start the new S process;
PATH is the full path to the version of S you want to run; ARGS is an
optional string of command-line arguments to pass to the S process.
Here is an example setting:
@example
(setq ess-s-versions-list 
      '( ("Splus64" "/usr/local/bin/Splus64")
         ("Splus64-j" "/usr/local/bin/Splus64" "-j")))
@end example
which will then allow you to do @kbd{M-x Splus64-j} to start  Splus64
with the corresponding command line arguments.


If you change the value of either @code{ess-s-versions} or
@code{ess-s-versions-list}, you should put them in your .emacs before
ess-site is loaded, since the new emacs functions are created when ESS
is loaded.




Sqpe (S-Plus running inside an emacs buffer) on Windows systems:
If you have an older version of S-Plus (S-Plus 6.1 for example) on your system,
ir can be started inside an emacs buffer with @kbd{M-x splus61}.  By
default, ESS will find versions of S-Plus located in the installation
directories that Insightful uses by default.  If your
versions of S-Plus are anywhere else, you will need to change the variable
@code{ess-SHOME-versions}.  To see
which defuns have been created for starting different versions of S-Plus,
type @kbd{M-x spl} and then hit [Tab].  You will then see if any defuns
for particular versions of S-Plus have been created.  These other versions of
S-Plus can also be started from the "ESS->Start Process->Other" menu.


@node ESS-help--assistance with viewing help, Philosophies for using ESS(S),iESS(S)--Inferior ESS processes,ESS for the S family
@comment  node-name,  next,  previous,  up
@section ESS-help--assistance with viewing help

ESS has built-in facilities for viewing help files from S.  @xref{Help}.


@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
@section Philosophies for using ESS[S]

The first is preferred, and configured for.  The second one can be
retrieved again, by changing emacs variables.

1: (preferred by the current group of developers):  The source code is
   real.  The objects are realizations of the source code.  Source
   for EVERY user modified object is placed in a particular directory
   or directories, for later editing and retrieval.

2: (older version): S objects are real.  Source code is a temporary
   realization of the objects.  Dumped buffers should not be saved.
   _We_strongly_discourage_this_approach_.  However, if you insist,
   add the following lines to your .emacs file:
@example
(setq ess-keep-dump-files 'nil)
(setq ess-delete-dump-files t)
(setq ess-mode-silently-save nil)
@end example
The second saves a small amount of disk space.  The first allows for
better portability as well as external version control for code.

@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
@section Scenarios for use (possibilities--based on actual usage)

We present some basic suggestions for using ESS to interact with S.
These are just a subset of approaches, many better approaches are
possible.  Contributions of examples of how you work with ESS are
appreciated (especially since it helps us determine priorities on
future enhancements)! (comments as to what should be happening are
prefixed by "##").
@display
1:  ##    Data Analysis Example (source code is real)
    ## Load the file you want to work with
    C-x C-f myfile.s

    ## Edit as appropriate, and then start up S-PLUS 3.x
    M-x S+3

    ## A new buffer *S+3:1* will appear.  Splus will have been started
    ## in this buffer.  The buffer is in iESS [S+3:1] mode.

    ## Split the screen and go back to the file editing buffer.
    C-x 2 C-x b myfile.s

    ## Send regions, lines, or the entire file contents to S-PLUS.  For regions,
    ## highlight a region with keystrokes or mouse and then send with:
    C-c C-r

    ## Re-edit myfile.s as necessary to correct any difficulties.  Add
    ## new commands here.  Send them to S by region with C-c C-r, or
    ## one line at a time with C-c C-n.

    ## Save the revised myfile.s with C-x C-s.

    ## Save the entire *S+3:1* interaction buffer with C-c C-s.  You
    ## will be prompted for a file name.  The recommended name is
    ## myfile.St.  With the *.St suffix, the file will come up in ESS
    ## Transcript mode the next time it is accessed from Emacs.



2:  ## Program revision example (source code is real)

    ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
    M-x S+3

    ## Load the file you want to work with
    C-x C-f myfile.s

    ## edit program, functions, and code in myfile.s, and send revised
    ## functions to S when ready with
    C-c C-f
    ## or highlighted regions with
    C-c C-r
    ## or individual lines with
    C-c C-n
    ## or load the entire buffer with
    C-c C-l

    ## save the revised myfile.s when you have finished
    C-c C-s



3:  ## Program revision example (S object is real)

    ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*)
    M-x S+3

    ## Dump an existing S object my.function into a buffer to work with
    C-c C-d my.function
    ## a new buffer named yourloginname.my.function.S will be created with
    ## an editable copy of the object.  The buffer is associated with the
    ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not
    ## exist after you log off.

    ## enter program, functions, and code into work buffer, and send
    ## entire contents to S-PLUS when ready
    C-c C-b

    ## Go to *S+3:1* buffer, which is the process buffer, and examine
    ## the results.
    C-c C-y
    ## The sequence C-c C-y is a shortcut for:  C-x b *S+3:1*

    ## Return to the work buffer (may/may not be prefixed)
    C-x C-b yourloginname.my.function.S
    ## Fix the function that didn't work, and resubmit by placing the
    ## cursor somewhere in the function and
    C-c C-f
    ## Or you could've selected a region (using the mouse, or keyboard
    ## via setting point/mark) and
    C-c C-r
    ## Or you could step through, line by line, using
    C-c C-n
    ## Or just send a single line (without moving to the next) using
    C-c C-j
    ## To fix that error in syntax for the "rchisq" command, get help
    ## by
    C-c C-v rchisq


4:    Data Analysis (S object is real)
    ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*)
    M-x S+3

    ## Work in the process buffer.  When you find an object that needs
    ## to be changed (this could be a data frame, or a variable, or a
    ## function), dump it to a buffer:
    C-c C-d my.cool.function

    ## Edit the function as appropriate, and dump back in to the
    ## process buffer
    C-c C-b

    ## Return to the S-PLUS process buffer
    C-c C-y
    ## Continue working.

    ## When you need help, use
    C-c C-v rchisq
    ## instead of entering:   help("rchisq")
@end display


@node Customization Examples and Solutions to Problems,  , Scenarios for use (possibilities--based on actual usage),ESS for the S family
@section Customization Examples and Solutions to Problems

1. Suppose that you are primarily an SPLUS 3.4 user, occasionally
   using S version 4, and sick and tired of the buffer-name *S+3*
   we've stuck you with.  Simply edit the "ess-dialect" alist entry in
   the essd-sp3.el and essd-s4.el files to be "S" instead of "S4" and
   "S+3".  This will ensure that all the inferior process buffer names
   are "*S*".

2. Suppose that you WANT to have the first buffer name indexed by
   ":1", in the same manner as your S-PLUS processes 2,3,4, and 5 (for
   you heavy simulation people).  Then uncomment the line in ess-site
   (or add after your (require 'ess-site) or (load "ess-site") command
    in your .emacs file, the line:
@example
(setq ess-plain-first-buffername nil)
@end example
   )

3. Fontlocking sometimes fails to behave nicely upon errors.  When
   Splus dumps, a mis-matched "  (double-quote) can result in the
   wrong font-lock face being used for the remainder of the buffer.

   Solution: add a " at the end of the "Dumped..." statement, to
   revert the font-lock face back to normal.