%% $Id: ESS_intro.tex,v 1.2 1999/11/16 20:58:36 ess Exp $
%%
%% $Log: ESS_intro.tex,v $
%% Revision 1.2 1999/11/16 20:58:36 ess
%% Martin suggested a small fix.
%%
%% Revision 1.1 1999/11/16 20:54:33 ess
%% Another bit of documentation
%%
%% Revision 1.11 1998/10/12 21:09:20 rossini
%% added andy's notes.
%%
%% Revision 1.10 1998/10/12 15:53:25 rossini
%% emacs clarification made (thanks Martin!).
%%
%% Revision 1.9 1998/10/12 15:48:16 rossini
%% Released in semi-final form.
%%
%%
\documentclass{article}
\addtolength{\textheight}{2in}
\addtolength{\textwidth}{1in}
\addtolength{\topmargin}{-1in}
\addtolength{\oddsidemargin}{-1.0in}
\usepackage{palatino}
\usepackage{html}
\title{A Quick Introduction to ESS}
\author{A.J. Rossini}
\begin{document}
\maketitle
This document can be found at
\begin{center}
\htmladdnormallink
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/}
\end{center}
The example file for this session is
\htmladdnormallink{rossini.example.R}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/rossini.example.R},
which can be retrieved (from the Biostat machines) by
\begin{verbatim}
cp ~rossini/public_html/talk/ESS_intro/rossini.example.R .
\end{verbatim}
to your current working directory. (note that the final ``.'' is very
important!).
For convenience, the \htmladdnormallink{latex}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/ESS\_intro.tex}
and \htmladdnormallink{postscript}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/ESS\_intro.ps}
versions are also available.
\section{Common Emacs Information}
\label{sec:emacs}
This is not a tutorial for Emacs. That is a subject for another session.
Basic notation for key sequences:
\begin{itemize}
\item \verb+[tab]+ is the TAB (indent) key.
\item \verb+C-k+ refers to holding down the control (ctrl) key \textbf{WHILE}
pressing ``k''.
\item \verb+M-k+ refers to pressing the Escape key (ESC),
\textbf{THEN} pressing ``k''.
\end{itemize}
\textbf{Only run one Emacs session}. This is a cardinal rule, that
you should try not to violate. To load in (visit) new files, do:
\begin{itemize}
\item \verb+C-x C-f+ (replaces current file in window with new)
\item \verb+C-x 4 C-f+ (load new file in different window)
\item \verb+C-x 5 C-f+ (load new file in different frame)
\end{itemize}
and to switch to another file, do
\begin{itemize}
\item \verb+C-x b+ (switch to new buffer in window)
\item \verb+C-x 4 b+ (replaces current file in different window)
\item \verb+C-x 5 b+ (replaces current file in different frame)
\end{itemize}
Buffers are the representations of the files you are editing. You can
treat them as the files themselves.
\subsection{Useful (X)Emacs Commands for UW Biostat}
\label{sec:emacs:uwbiostat}
In the following, \emph{``Emacs''} can be used instead of
\emph{``XEmacs''}.
This section is thanks to \htmladdnormallink{Andy
Dunning}{mailto:adunning@biostat.washington.edu} and
\htmladdnormallink{Greg Warnes}{mailto:warnes@biostat.washington.edu}.
It's also available as a \htmladdnormallink{crib sheet text document}
{http://www.biostat.washington.edu/\~{}rossini/talk/ESS\_intro/emacs.txt}.
\begin{verbatim}
USEFUL XEMACS COMMANDS
======================
STARTING XEMACS (Currently on GIBSON, GORN, SOL, ATLAS, ABACUS)
---------------
rsh <machine> login to machine <machine>
xemacs <filename> start xemacs, edit <filename>
xemacs -f S start xemacs, run S-plus
xemacs -nw start xemacs in _text_ mode (nw="No Window")
(useful over telnet session from home)
ANY EMACS BUFFER
----------------
MOVING AROUND
-------------
C-v Move forward one screenful
M-v Move backward one screenful
C-l Clear screen and redisplay everything
M- -> Meta-<right> - moves forward a word
M- <- Meta-<left> - moves back a word
M- |^ Meta-<up> - move up a paragraph
M- V Meta-<down> - move down a paragraph
M- < Meta-<less than> - move to end of file
CUT AND PASTE
-------------
C-d _D_elete
C-k _K_ill from the cursor position to end of line
C-y Recover/Paste (_Y_ank) killed text (repeat to copy)
M-y recover former killed text (after C-y. Repeat to go
back through stack).
C-x u _U_ndo
LOADING/SAVING FILES
--------------------
C-x C-f _F_ind a file
C-x C-s _S_ave the file
If you find a second file with C-x C-f, the first file remains
inside Emacs. You can switch back to it by finding it again with
C-x C-b. This way you can get quite a number of files inside Emacs.
MANAGING BUFFERS / WINDOWS
--------------------------
C-x 0 Move between windows
C-x 1 One window (i.e., kill all other windows).
C-x b Switch to new _b_uffer
C-x C-b List _b_uffers
SEARCH and REPLACE
------------------
M-x (then) replace-string
Replace string
C-s _S_earch forward - repeat to move to next occurence
C-r Search _r_everse - repeat to move to previous occurence
MISC
----
C-h or C-h ? _H_elp
C-h c (command) _H_elp on this _c_ommand
C-u 8 (character or command)
Repeat character or command 8 times
C-g Stop, undo, unhang.
C-x C-c stop editing and exit (_c_lose) Emacs
STARTING SPLUS / ESS
--------------------
M-x S Start _S_-plus process buffer
M-x S-mode Change mode of current buffer to S-plus code editing
S EXECUTION BUFFER (Usually named "*S*" or similar, mode line says "iESS")
------------------
C-c C-d _D_ump S-plus object or function into new editing
buffer.
C-c C-v xxx get S-plus help on "xxx"
S CODE EDITING BUFFER (Usually named for the file being edited, mode line
--------------------- says "ESS[S]")
C-c C-j Send line to S
C-c C-n Send line to S and move down to _n_ext line
C-c C-r Send highlighted _r_egion to S
C-c C-b Send whole _b_uffer to S
C-c C-f Send _f_unction where cursor is to S
C-c C-v xxx get S-plus help on "xxx"
\end{verbatim}
\section{Replacing Command-line Usage}
\label{sec:commandline}
\subsection{Start-up}
\label{sec:commandline:startup}
\begin{enumerate}
\item To run from the command-line in a non-windowing environment:
\begin{verbatim}
xemacs -f S
\end{verbatim}
\item To run from the command-line in a windowing environment:
\begin{verbatim}
xemacs -f S &
\end{verbatim}
\end{enumerate}
(note that depending on the system, you might be using \verb+emacs+,
not \verb+xemacs+).
\textbf{Optional: } The first time that one runs this, you should
construct the object list. This is done by:
\begin{verbatim}
M-x ess-create-object-name-db
\end{verbatim}
or
\begin{verbatim}
M-x ess-create-obj[tab]
\end{verbatim}
where \verb+[tab]+ is the TAB key.
One can replace \verb+S+ with \verb+R+ or \verb+XLS+, to run a
different version. The object database feature currently only works
with Splus and R.
\subsection{Replacing Command-line Usage}
\label{sec:commandline:usage}
To enter commands, you generally need to be at a command prompt (i.e.
``\verb+> +''). But there are some nice exceptions.
The follow applies primarily to \verb+Splus+ and \verb+R+.
\begin{enumerate}
\item To get help on a function (help(``lm'')) without spoiling your
input line: \verb+C-c C-v+
\item Completion of objects (functions and data):
\begin{enumerate}
\item \verb+C-c [tab]+
\item \verb+[tab]+ (sometimes).
\end{enumerate}
\item Search command-line history ``manually'', matching on current input
\begin{enumerate}
\item backwards: \verb+M-p+
\item forwards: \verb+M-n+
\end{enumerate}
\item Complete current line based on command-line history:
\begin{enumerate}
\item backwards: \verb+\C-[uparrow]-p+
\item forwards: \verb+M-n+
\end{enumerate}
\item If you are reviewing old commands, to re-enter it one (with the
cursor on the line): \verb+[return]+.
\end{enumerate}
Many other commands, as well...
\section{Replacing Cut-and-Paste}
\label{sec:cutpaste}
The next stage of statistics package usage is usually to cut-and-paste
from an editor. Since we are within an editor, this is moot.
\textbf{Use the following suffices for your files:}
\begin{itemize}
\item \verb+.S+, such as \verb+critical_simulation.S+
\item \verb+.R+, such as \verb+speedy_simulation.R+
\end{itemize}
\subsection{Cut and Paste}
\label{sec:cutpaste:usual}
You \textbf{can} cut and paste. It's pretty identical, and a bit ugly.
\subsection{Efficient Methods 1}
\label{sec:cutpaste:eff1}
\textbf{This works from the process (inferior ESS, or iESS) buffer}
One improvement is to use a \verb+source()+-like facility.
\begin{enumerate}
\item To source a file into Splus (within ESS): \verb+C-c C-l+ (load file)
\item To find what the errors are (if any): \verb+C-c `+ (backquote).
\end{enumerate}
The latter will tell you what the error is. You'll have to go back to
the file and edit it.
\subsection{Efficient Methods 2}
\label{sec:cutpaste:eff2}
\textbf{This works from the editing (ESS) buffer}
Better yet, use a file, and send material from the file straight to
the process. This works if the file ends in the proper suffix (and
hence, the mode at the bottom should say ``ESS'').
The following is possible:
\begin{itemize}
\item Send current line to S: \verb+C-c C-j+
\item Send current function to S (assumes the cursor is in the
function body): \verb+C-c C-f+.
\item Send current region (highlighted) to S \verb+C-c C-r+
\item Send whole buffer/file to S \verb+C-c C-b+
\end{itemize}
\section{Editing}
\label{sec:edit}
\textbf{This works from the editing (ESS) buffer}
See Section~\ref{sec:cutpaste:eff2} for communication between the code
buffer and the process buffer.
The help commands and object completion commands (only \verb+C-c [TAB]+
version) work.
Syntax-highlighting and formatting are present. For comment indentation:
\begin{enumerate}
\item \verb+#+ gets moved to the right-side of the line
\item \verb+##+ is placed at the current indentation level
\item \verb+###+ is placed flush-left.
\end{enumerate}
To dump an object into a buffer (for editing, saving, possible reloading):
\begin{enumerate}
\item \verb+C-c C-d+ dumps the named object into an editing buffer (in
ESS mode).
\end{enumerate}
\section{Advanced Usage}
\label{sec:advanced}
\begin{itemize}
\item preliminary integration with noweb, for literate programming and
data analysis (another talk)
\item Has a transcript mode for recreating work and providing
demonstrations.
\item Except for object-completion, everything mentioned here works
\textbf{identically} for Stata, XLispStat, and SAS.
\item Makes versioning (version control, document revision history)
simple.
\end{itemize}
\end{document}
