doc/README.XLispStat

   1 -*- indented-text -*-
   2
   3 $Revision: 5.1 $
   4
   5
   6 ESS: Using the XLispStat family of statistical languages
   7 ========================================================
   8
   9 This module is currently undergoing development.  It is not as stable
  10 as the S language support.  However, it should be functional, if
  11 slightly buggy.  Please send any suggestions and bug reports to
  12 ess-bugs@stat.math.ethz.ch.
  13
  14 ESS (originally S-mode) was initially designed for use with S and
  15 S-PLUS(tm).  However, it has been recently extended to support other
  16 languages, including XLispStat.  If you are looking for a stable, old
  17 XLispStat mode, we suggest ILISP and the recent modifications.
  18 However, those features and new advanced features are being merged
  19 with the development of ESS[XLS], which is similar in behavior to the
  20 interface for S (unlike ILISP).  We denote by _XLS_ the LispStat
  21 languages XLispStat and ViSta (though the ViSta program is called by
  22 ViSta).  We denote by _Emacs_, one of the GNU family of editors,
  23 either Emacs (as developed and maintained by the Free Software
  24 Foundation) or XEmacs (which a derivative work).
  25
  26 The following is covered in this document:
  27 - Editing files.
  28 - running an XLS process as an inferior process to Emacs (we
  29   include
  30 - using transcripts.
  31 - Scenarios for use (possibilities, based on actual usage)
  32 - Philosophies
  33
  34 We assume that you are familiar with Emacs terminology and syntax:
  35 file, buffer, region, description of keys etc.  If not, please read
  36 the New Users guide (found in the info pages, "C-h i" (by pressing
  37 control h, i) or Tutorial, "C-h t").
  38
  39
  40 ESS[XLS]: Editing Files
  41 =====================
  42
  43 ESS[XLS] is the mode for editing XLS language files.  This mode handles:
  44
  45 - proper indenting, generated by both [Tab] and [Return].
  46 - color and font choices based on syntax.
  47 - ability to send the contents of a single buffer, regions, lines, and
  48   functions to an inferior process, if one is currently running.
  49 - ability to switch between processes which would be the target of the
  50   buffer (for the above).
  51 - The ability to request help from a process for variables and
  52   functions, and to have the results sent into a separate buffer.
  53
  54 It should be automatically turned on when loading a file with the
  55 suffix *.lsp or as set in ess-site.el.  However, one will have to
  56 start up an inferior process to take advantage of the interactive
  57 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 send the contents of a single buffer, regions, lines, and
  69   functions to an inferior process, if one is currently running.
  70 - The ability to request help from a process for variables and
  71   functions, and to have the results sent into a separate buffer.
  72 - interactive history mechanism
  73 - transcript recording and editing
  74
  75 To start up this mode, use:
  76    M-x XLS
  77
  78
  79 ESS-help: assistance with viewing help
  80 ======================================
  81
  82 - obtain help files in a separate buffer for later viewing.
  83 - send examples to XLS for evaluation.
  84
  85
  86 Scenarios for use
  87 =================
  88
  89 We present some basic suggestions for using ESS to interact with XLS.
  90 These are just a subset of approaches, many better approaches are
  91 possible.  Contributions of examples of how you work with ESS are
  92 appreciated (especially since it helps us determine priorities on
  93 future enhancements)! (comments as to what should be happening are
  94 prefixed by "##").
  95
  96 1:  ## Start up XLispStat, in a process buffer (this will be *XLS:1*)
  97     M-x XLS
  98     ## Load a buffer to work from
  99     C-x C-f todays_work.lsp
 100     ## enter program, functions, and code into work buffer, and send
 101     ## entire contents to XLispStat when ready
 102     C-c C-b
 103     ## Go to *XLS:1* buffer, which is the process buffer, and examine
 104     ## the results.
 105     C-c C-y
 106     ## the above is a shortcut for:  C-x b *XLS:1*
 107     ## Return to the work buffer (may/may not be prefixed)
 108     C-x C-b 971103work.S
 109     ## Fix the function that didn't work, and resubmit by placing the
 110     ## cursor somewhere in the function and
 111     C-c C-f
 112     ## Or you could've selected a region (using the mouse, or keyboard
 113     ## via setting point/mark) and
 114     C-c C-r
 115     ## Or you could step through, line by line, using
 116     C-c C-n
 117     ## Or just send a single line (without moving to the next) using
 118     C-c [RETURN]
 119     ## where [RETURN] is the return key.
 120     ## To fix that error in syntax for the "normal-rand" command, get
 121     ## help by
 122     C-c C-v normal-rand
 123
 124 2:  ## Load the file you want to work with
 125     C-x C-f file.lsp
 126     ## Edit as appropriate, and then start up XLispStat
 127     M-x XLS
 128     ## Go back to the file editing buffer
 129     C-x b file.lsp
 130     ## send regions, lines, or the entire file contents to XLispStat
 131     ## (the last one is demonstrated below)
 132     C-c C-b