-*- indented-text -*-

$Revision: 5.1 $


ESS: Using the XLispStat family of statistical languages
========================================================

This module is currently undergoing development.  It is not as stable
as the S language support.  However, it should be functional, if
slightly buggy.  Please send any suggestions and bug reports to
ess-bugs@stat.math.ethz.ch.

ESS (originally S-mode) was initially designed for use with S and
S-PLUS(tm).  However, it has been recently extended to support other
languages, including XLispStat.  If you are looking for a stable, old
XLispStat mode, we suggest ILISP and the recent modifications.
However, those features and new advanced features are being merged
with the development of ESS[XLS], which is similar in behavior to the
interface for S (unlike ILISP).  We denote by _XLS_ the LispStat
languages XLispStat and ViSta (though the ViSta program is called by
ViSta).  We denote by _Emacs_, one of the GNU family of editors,
either Emacs (as developed and maintained by the Free Software
Foundation) or XEmacs (which a derivative work).

The following is covered in this document:
- Editing files.
- running an XLS process as an inferior process to Emacs (we
  include 
- using transcripts.
- Scenarios for use (possibilities, based on actual usage)
- Philosophies

We assume that you are familiar with Emacs terminology and syntax:
file, buffer, region, description of keys etc.  If not, please read
the New Users guide (found in the info pages, "C-h i" (by pressing
control h, i) or Tutorial, "C-h t").


ESS[XLS]: Editing Files
=====================

ESS[XLS] is the mode for editing XLS language files.  This mode handles:

- proper indenting, generated by both [Tab] and [Return].
- color and font choices based on syntax.
- ability to send the contents of a single buffer, regions, lines, and 
  functions to an inferior process, if one is currently running.
- ability to switch between processes which would be the target of the 
  buffer (for the above).
- The ability to request help from a process for variables and
  functions, and to have the results sent into a separate buffer.

It should be automatically turned on when loading a file with the
suffix *.lsp or as set in ess-site.el.  However, one will have to
start up an inferior process to take advantage of the interactive
features.


iESS: Inferior ESS processes.
=============================

iESS (inferior ESS) is the mode for interfacing with active
statistical processes (programs).  This mode handles:

- proper indenting, generated by both [Tab] and [Return].
- color and font highlighting based on syntax.
- ability to send the contents of a single buffer, regions, lines, and 
  functions to an inferior process, if one is currently running.
- The ability to request help from a process for variables and
  functions, and to have the results sent into a separate buffer.
- interactive history mechanism
- transcript recording and editing

To start up this mode, use:
   M-x XLS


ESS-help: assistance with viewing help
======================================

- obtain help files in a separate buffer for later viewing.
- send examples to XLS for evaluation.


Scenarios for use
=================

We present some basic suggestions for using ESS to interact with XLS.
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 "##").

1:  ## Start up XLispStat, in a process buffer (this will be *XLS:1*) 
    M-x XLS
    ## Load a buffer to work from
    C-x C-f todays_work.lsp
    ## enter program, functions, and code into work buffer, and send
    ## entire contents to XLispStat when ready
    C-c C-b
    ## Go to *XLS:1* buffer, which is the process buffer, and examine
    ## the results.
    C-c C-y
    ## the above is a shortcut for:  C-x b *XLS:1*
    ## Return to the work buffer (may/may not be prefixed)
    C-x C-b 971103work.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 [RETURN]
    ## where [RETURN] is the return key.
    ## To fix that error in syntax for the "normal-rand" command, get
    ## help by
    C-c C-v normal-rand

2:  ## Load the file you want to work with
    C-x C-f file.lsp
    ## Edit as appropriate, and then start up XLispStat
    M-x XLS
    ## Go back to the file editing buffer
    C-x b file.lsp
    ## send regions, lines, or the entire file contents to XLispStat
    ## (the last one is demonstrated below)
    C-c C-b