1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
4 @settitle ESS --- Emacs Speaks Statistics
5 @comment %**end of header
11 @title ESS --- Emacs Speaks Statistics
12 ESS @w{version @ESSVER}
14 @author The ESS Developers (A.J. Rossini, R.M. Heiberger, K. Hornik,
15 @author M. Maechler, R.A. Sparapani and S.J. Eglen)
16 @c @author (Formerly by: Doug Bates, Ed Kademan, Frank Ritter
17 @c @author and David Smith)
22 @author Current Documentation by The ESS Developers
23 @author Copyright @copyright{} 2002--2005 The ESS Developers
24 @author Copyright @copyright{} 1996--2001 A.J. Rossini
25 @c (@email{rossini@@biostat.washington.edu})
26 @c @author Department of Biostatistics
27 @c @author University of Washington, USA.
28 @author Original Documentation by David M. Smith
29 @author Copyright @copyright{} 1992--1995 David M. Smith
30 @c (@email{D.M.Smith@@lancaster.ac.uk})
31 @c @author Department of Mathematics and Statistics
32 @c @author Lancaster University, UK
34 @c @vskip 0pt plus 1filll
36 @author Permission is granted to make and distribute verbatim copies of this
37 @author manual provided the copyright notice and this permission notice are
38 @author preserved on all copies.
39 @author Permission is granted to copy and distribute modified versions of this
40 @author manual under the conditions for verbatim copying, provided that the
41 @author entire resulting derived work is distributed under the terms of a
42 @author permission notice identical to this one.
47 @majorheading ESS --- Emacs Speaks Statistics
51 * ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS, Stata, XLisp-Stat).
53 @c node-name, next, previous, up
54 @node Top, Introduction, (dir), (dir)
55 @top ESS: Emacs Speaks Statistics
70 @c Bates, Ed Kademan, Frank Ritter and David Smith).
72 Emacs Speaks Statistics (ESS) provides an intelligent, consistent
73 interface between the user and the software. ESS interfaces with
74 SAS, S-PLUS, R, BUGS and other statistical analysis packages under
75 the Unix, Microsoft Windows, and Apple Mac operating systems. ESS
76 is itself a package within the emacs text editor and uses emacs
77 features to streamline the creation and use of statistical software.
78 ESS knows the syntax and grammar of statistical analysis packages
79 and provides consistent display and editing features based on that
80 knowledge. ESS assists in interactive and batch execution of
81 statements written in these statistical analysis languages.
87 * Introduction:: Overview of features provided by this package
88 * Installation:: Installing ESS on your system
90 * Interactive ESS:: Interacting with statistical programs
91 * Entering commands:: Interacting with the ESS process
92 * Transcript Mode:: Manipulating saved transcript files
94 * ESS for the S family::
95 * Editing:: How to create/edit objects and functions
96 * Editing R documentation files::
97 * Help:: Reading help files
102 * Miscellaneous:: Other features of ESS
103 * Mailing lists/bug reports:: How to get assistance with ESS
104 * Customization:: Customizing ESS
108 * Variable and command index::
111 @c --- The Detailed Node Listing ---
113 @c Introduction to ESS
115 @c * Features:: Why should I use ESS?
117 @c * Credits:: Authors of and contributors to ESS
118 @c * Latest version:: Getting the latest version of ESS
119 @c * Manual:: How to read this manual
121 @c Installing ESS on your system
122 @c * Unix installation:: Installing ESS on your Unix system
123 @c * Microsoft Windows installation:: Installing ESS on your MS Windows system
124 @c * Requirements:: emacs, Operating Systems and Statistical Packages
125 @c * System dependent:: Other variables you may need to change
127 @c Starting the ESS process
129 @c * Multiple ESS processes::
130 @c * ESS processes on Remote Computers::
131 @c * Customizing startup:: Changing the startup actions
133 @c Help for the S family
135 @c * ESS(S)--Editing files::
136 @c * iESS(S)--Inferior ESS processes::
137 @c * Handling and Reusing Transcripts::
138 @c * ESS-help--assistance with viewing help::
139 @c * Philosophies for using ESS(S)::
140 @c * Scenarios for use (possibilities--based on actual usage)::
141 @c * Customization Examples and Solutions to Problems::
145 @c * ESS(SAS)--Design philosophy::
146 @c * ESS(SAS)--Editing files::
147 @c * iESS(SAS)--Interactive SAS processes::
148 @c * ESS(SAS)--Batch SAS processes::
149 @c * ESS(SAS)--Function keys for batch processing::
150 @c * ESS(SAS)--TAB key::
151 @c * ESS(SAS)--Usage scenarios::
152 @c * iESS(SAS)--Common problems::
153 @c * ESS(SAS)--MS Windows::
155 @c Interacting with the ESS process
157 @c * Command-line editing:: Entering commands and fixing mistakes
158 @c * Completion:: Completion of object names
159 @c * Completion details:: Advanced completion concepts
160 @c * Transcript:: Manipulating the transcript
161 @c * Command History:: Command History
162 @c * History expansion:: References to historical commands
163 @c * Hot keys:: Hot keys for common commands
164 @c * Statistical Process running in ESS?::
165 @c * Other:: Other commands provided by inferior-ESS
167 @c Manipulating the transcript
169 @c * Last command:: Manipulating the output from the last command
170 @c * Process buffer motion:: Viewing older commands
171 @c * Transcript resubmit:: Re-submitting commands from the transcript
172 @c * Saving transcripts:: Keeping a record of your S session
174 @c Editing S functions
176 @c * Edit buffer:: Edit objects in a specialized buffer
177 @c * Loading:: Loading source files into the ESS process
178 @c * Error Checking:: Detecting errors in source files
179 @c * Evaluating code:: Sending code to the ESS process
180 @c * Indenting:: Indenting and formatting @Sl{} code
181 @c * Other edit buffer commands:: Commands for motion, completion and more
182 @c * Source Files:: Maintaining @Sl{} source files
183 @c * Source Directories:: Names and locations of dump files
185 @c Manipulating saved transcript files
187 @c * Resubmit:: Resubmitting commands from the transcript file
188 @c * Clean:: Cleaning transcript files
190 @c Other features of ESS
192 @c * Highlighting:: Syntactic highlighting of buffers
193 @c * Graphics:: Using graphics with ESS
194 @c * Object Completion::
196 @c Using graphics with ESS
198 @c * printer:: The printer() graphics driver
199 @c * X11:: The X11() (and other X-windows based) driver
201 @c Bugs and Bug Reporting, Mailing Lists
204 @c * Reporting Bugs::
209 @c * Variables:: Variables for customization
210 @c * Hooks:: Customizing ESS with hooks
211 @c * Keybindings:: Changing the default ESS keybindings
213 @c Variables for customization
215 @c * Variables for starting ESS:: Variables for starting ESS
216 @c * Dump file variables:: Variables for dump files
217 @c * Indentation variables:: Variables controlling indentation
218 @c * Variables controlling interaction:: Variables controlling interaction
219 @c with the ESS process
223 @comment node-name, next, previous, up
224 @node Introduction, Installation, Top, Top
225 @chapter Introduction to ESS
228 The S family (@Sl{}, Splus and R) and SAS statistical analysis packages
229 provide sophisticated statistical and graphical routines for manipulating
230 data. @b{E}macs @b{S}peaks @b{S}tatistics (ESS) is based on the merger
231 of two pre-cursors, S-mode and SAS-mode, which provided support for the
232 S family and SAS respectively. Later on, Stata-mode was also incorporated.
234 ESS provides a common, generic, and useful interface, through emacs, to
235 many statistical packages. It currently supports the S family, SAS, BUGS,
236 Stata and XLisp-Stat with the level of support roughly in that order.
238 A bit of notation before we begin. @emph{emacs} refers to both
239 @emph{GNU Emacs} by the Free Software Foundation, as well as
240 @emph{XEmacs} by the XEmacs Project. The emacs major
241 mode @code{ESS[language]}, where @code{language} can take values such as
242 @code{S}, @code{SAS}, or @code{XLS}. The inferior process interface
243 (the connection between emacs and the running process) referred to as inferior ESS
244 (@code{iESS}), is denoted in the modeline by @code{ESS[dialect]}, where
245 @code{dialect} can take values such as @code{S3}, @code{S4}, @code{S+3},
246 @code{S+4}, @code{S+5}, @code{S+6}, @code{S+7}, @code{R}, @code{XLS}, @code{VST}, @code{SAS}.
248 Currently, the documentation contains many references to @cite{`S'}
249 where actually any supported (statistics) language is meant, i.e., `S'
250 could also mean `XLisp-Stat' or `SAS'.
252 @cindex interactive use of S
254 @cindex using S interactively
255 For exclusively interactive users of S, ESS provides a number of
256 features to make life easier. There is an easy to use command history
257 mechanism, including a quick prefix-search history. To reduce typing,
258 command-line completion is provided for all @Sl{} objects and ``hot
259 keys'' are provided for common @Sl{} function calls. Help files are
260 easily accessible, and a paging mechanism is provided to view them.
261 Finally, an incidental (but very useful) side-effect of ESS is that a
262 transcript of your session is kept for later saving or editing.
264 @cindex transcripts of S sessions
265 No special knowledge of Emacs is necessary when using @Sl{}
266 interactively under ESS.
268 @cindex programming in S
269 For those that use @Sl{} in the typical edit--test--revise cycle when
270 programming @Sl{} functions, ESS provides for editing of @Sl{} functions
271 in Emacs edit buffers. Unlike the typical use of @Sl{} where the editor
272 is restarted every time an object is edited, ESS uses the current Emacs
273 session for editing. In practical terms, this means that you can edit
274 more than one function at once, and that the ESS process is still
275 available for use while editing. Error checking is performed on
276 functions loaded back into S, and a mechanism to jump directly to the
277 error is provided. ESS also provides for maintaining text versions of
278 your @Sl{} functions in specified source directories.
281 * Features:: Why should I use ESS?
283 * Credits:: Authors of and contributors to ESS
284 * Latest version:: Getting the latest version of ESS
285 * Manual:: How to read this manual
288 @comment node-name, next, previous, up
289 @node Features, New features, Introduction, Introduction
290 @section Why should I use ESS?
292 Statistical packages are powerful software systems for manipulating and
293 analyzing data, but their user interfaces often leave something something
294 to be desired: they offer weak editor functionality and they differ
295 among themselves so markedly that you have to re-learn how to do those
296 things for each package. ESS is a package which is designed to make
297 editing and interacting with statistical packages more uniform,
298 user-friendly and give you the power of emacs as well.
300 ESS provides several features which make it easier to interact with the
301 ESS process (a connection between your buffer and the statistical
302 package which is waiting for you to input commands). These include:
306 @b{Command-line editing} for fixing mistakes in commands before they are
307 entered. The @samp{-e} flag for S-plus provides something similar to
308 this, but here you have the full range of Emacs commands rather than a
309 limited subset. However, other packages such as XLisp-Stat and S3 do not
310 necessarily have features like this built-in.
311 @xref{Command-line editing}.
314 @b{Searchable command history} for recalling previously-submitted
315 commands. This provides all the features of the @samp{Splus -e} history
316 mechanism, plus added features such as history searching.
317 @xref{Command History}.
320 @b{Command-line completion} of both object and file names for quick
321 entry. This is similar to @code{tcsh}'s facility for filenames; here it
322 also applies to object names and list components.
326 @b{Hot-keys} for quick entry of commonly-used commands in `S' such as
327 @code{objects()} and @code{search()}.
331 @b{Transcript recording} for a complete record of all the actions in an
336 @b{Interface to the help system}, with a specialized mode for viewing S
342 If you commonly create or modify @Sl{} functions, you will have found
343 the standard facilities for this (the @samp{fix()} function, for
344 example) severely limiting. Using S's standard features, one can only
345 edit one function at a time, and you can't continue to use @Sl{} while
346 editing. ESS corrects these problems by introducing the following
351 @b{Object editing}. ESS allows you to edit more than one function
352 simultaneously in dedicated Emacs buffers. The ESS process may
353 continue to be used while functions are being edited.
357 @b{A specialized editing mode} for @Sl{} code, which provides syntactic
358 indentation and highlighting.
362 @b{Facilities for loading and error-checking source files}, including a
363 keystroke to jump straight to the position of an error in a source file.
364 @xref{Error Checking}.
367 @b{Source code revision maintenance}, which allows you to keep historic
368 versions of @Sl{} source files.
372 @b{Facilities for evaluating @Sl{} code} such as portions of source
373 files, or line-by-line evaluation of files (useful for debugging).
374 @xref{Evaluating code}.
377 Finally, ESS provides features for re-submitting commands from saved
378 transcript files, including:
383 @b{Evaluation of previously entered commands}, stripping away
385 @xref{Transcript resubmit}.
389 @comment node-name, next, previous, up
390 @node New features, Credits, Features, Introduction
391 @section New features in ESS
393 @include newfeat.texi
395 @comment node-name, next, previous, up
396 @node Credits, Latest version, New features, Introduction
397 @section Authors of and contributors to ESS
399 @include credits.texi
401 @comment node-name, next, previous, up
402 @node Latest version, Manual, Credits, Introduction
403 @section Getting the latest version of ESS
405 @include getting.texi
407 @comment node-name, next, previous, up
408 @node Manual, , Latest version, Introduction
409 @section How to read this manual
411 If you need to install ESS, read @ref{Installation} for details on what
412 needs to be done before proceeding to the next chapter.
414 In this manual we use the standard notation for describing the
415 keystrokes used to invoke certain commands. @kbd{C-<chr>} means hold
416 the CONTROL key while typing the character <chr>. @kbd{M-<chr>} means
417 hold the META or EDIT or ALT key down while typing <chr>. If there is no
418 META, EDIT or ALT key, instead press and release the ESC key and then
421 All ESS commands can be invoked by typing @kbd{M-x command}. Most of
422 the useful commands are bound to keystrokes for ease of use. Also, the
423 most popular commands are also available through the emacs menubar, and
424 finally, if available, a small subset are provided on the toolbar.
425 Where possible, keybindings are similar to other modes in emacs to
426 strive for a consistent user interface within emacs, regardless of the
427 details of which programming language is being edited, or process being
430 Some commands, such as @kbd{M-x R} can accept an optional `prefix'
431 argument. To specify the prefix argument, you would type @kbd{C-u}
432 before giving the command. e.g. If you type @kbd{C-u M-x R}, you will
433 be asked for command line options that you wish to invoke the R process
436 Emacs is often referred to as a `self-documenting' text editor. This
437 applies to ESS in two ways. First, limited documentation about each ESS
438 command can be obtained by typing @kbd{C-h f}. For example, if you type
439 @kbd{C-h f ess-eval-region}, documentation for that command will appear
440 in a separate *Help* buffer. Second, a complete list of keybindings
441 that are available in each ESS mode and brief description of that mode
442 is available by typing @kbd{C-h m} within an ESS buffer.
444 Emacs is a versatile editor written in both C and lisp; ESS is written
445 in the Emacs lisp dialect (termed `elisp') and thus benefits from the
446 flexible nature of lisp. In particular, many aspects of ESS behaviour
447 can be changed by suitable customization of lisp variables. This manual
448 mentions some of the most frequent variables. A full list of them
449 however is available by using the Custom facility within emacs. (Type
450 @kbd{M-x customize-group RET ess RET} to get started.)
451 @ref{Customization} provides details of common user variables you can
452 change to customize ESS to your taste, but it is recommended that you
453 defer this section until you are more familiar with ESS.
455 @comment node-name, next, previous, up
456 @node Installation, Interactive ESS, Introduction, Top
457 @chapter Installing ESS on your system
460 The following section details those steps necessary to get ESS running
464 * Unix installation:: Installing ESS on your Unix system
465 * Microsoft Windows installation:: Installing ESS on your MS Windows system
466 * Requirements:: emacs, Operating Systems and Statistical Packages
469 @c FIXME: the following contains @node s *and* is also included by readme.texi
470 @c ----- which does *not* include 'requires.texi'
471 @c ==> *must* give node pointer problems!
472 @include inst_tar.texi
474 @node Requirements, , Microsoft Windows installation, Installation
475 @comment node-name, next, previous, up
476 @section Requirements
477 @include requires.texi
480 @comment node-name, next, previous, up
481 @node Interactive ESS, Entering commands, Installation, Top
482 @chapter Interacting with statistical programs
484 As well as using ESS to edit your source files for statistical programs,
485 you can use ESS to run these statistical programs. In this chapter, we
486 mostly will refer by example to running S from within emacs. The emacs
487 convention is to name such processes running under its control as
488 `inferior processes'. This term can be slightly misleading, in which
489 case these processes can be thought of `interactive processes'. Either
490 way, we use the term `iESS' to refer to the Emacs mode used to interact
491 with statistical programs.
494 @comment node-name, next, previous, up
497 * Multiple ESS processes::
498 * ESS processes on Remote Computers::
499 * S+elsewhere and ESS-elsewhere::
500 * Customizing startup::
503 @node Starting up, Multiple ESS processes, Interactive ESS, Interactive ESS
504 @section Starting an ESS process
508 To start an @Sl{} session, simply type @kbd{M-x S RET}.
511 @cindex ESS process directory
512 @cindex starting directory
513 @cindex working directory
516 S will then (by default) ask the question
518 S starting data directory?
521 Enter the name of the directory you wish to start @Sl{} from (that is,
522 the directory you would have @code{cd}'d to before starting @Sl{} from
523 the shell). This directory should have a @file{.Data} subdirectory.
525 You will then be popped into a buffer
526 @cindex ESS process buffer
527 @cindex process buffer
528 with name @samp{*S*} which will be used
529 for interacting with the ESS process, and you can start entering commands.
532 @comment node-name, next, previous, up
533 @node Multiple ESS processes, ESS processes on Remote Computers, Starting up, Interactive ESS
534 @section Running more than one ESS process
535 @cindex Multiple ESS processes
537 ESS allows you to run more than one ESS process simultaneously in the
538 same session. Each process has a name and a number; the initial process
539 @cindex process names
540 (process 1) is simply named (using S-PLUS as an example) @samp{S+3:1}.
541 @comment You may start a new process by passing a numeric argument to
542 @comment @kbd{M-x S}. For example, typing @kbd{ESC 2 M-x S} starts up
543 @comment an ESS process with name @samp{S2}, in a buffer whose name
544 @comment is initially @samp{*S2*}.
545 The name of the process is shown in the mode line in square brackets
546 (for example, @samp{[S+3:2]}); this is useful if the process buffer is
547 renamed. Without a prefix argument, @kbd{M-x S} starts a new ESS
548 process, using the first available process number. With a prefix
549 argument (for R), @kbd{C-u M-x R} allows for the specification of
550 command line options.
552 @pindex ess-request-a-process
553 You can switch to any active ESS process with the command
554 @samp{M-x ess-request-a-process}. Just enter the name of the process
555 you require; completion is provided over the names of all running S
556 processes. This is a good command to consider binding to a global key.
558 @c SJE - commented outl the default behaviour now is to label *S* rather
560 @c @vindex ess-plain-first-buffername
561 @c For the predecessor to ESS (S-mode 4.8), the initial process was not
562 @c visibly numbered, i.e. S instead of S1 was used in the mode-line. To
563 @c obtain this behavior, set the variable @code{ess-plain-first-buffername}
564 @c to @code{t}. See @file{ess-site} for how to set this for all users.
567 @comment node-name, next, previous, up
568 @node ESS processes on Remote Computers, S+elsewhere and ESS-elsewhere, Multiple ESS processes, Interactive ESS
569 @section ESS processes on Remote Computers
570 @cindex Remote Computers
572 @pindex ESS-elsewhere
575 ESS works with processes on remote computers as easily as with
576 processes on the local machine. The recommended way to access a
577 statistical program on remote computer is to start it from a telnet or
578 ssh buffer and then connect ESS to that buffer.
581 @item Start a new telnet or ssh buffer and connect to the remote computer
582 (e.g. use @samp{M-x telnet} or @samp{M-x ssh}; ssh.el is available at
583 @uref{ftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.el}).
585 @item Start the ESS process on the remote machine, for example with one of
586 the commands @samp{Splus}, or @samp{R}, or @samp{sas -stdio}.
588 @item Enter the ESS command @samp{M-x ess-remote}. You will be prompted for
589 a program name. Enter @samp{sp6} or @samp{r} or @samp{sas} or another
590 valid name. Your telnet process is now known to ESS. All the usual
591 ESS commands (@samp{C-c C-n} and its relatives) now work with the S
592 language processes. For SAS you need to use a different command
593 @samp{C-c i} (that is a regular @samp{i}, not a @samp{C-i}) to send
594 lines from your @file{myfile.sas} to the remote SAS process.
595 @samp{C-c i} sends lines over invisibly.
596 @c and lets SAS display them formatted correctly as in a SAS log file.
597 With ess-remote you get teletype behavior---the data input, the
598 log, and the listing all appear in the same buffer. To make this work,
599 you need to end every PROC and DATA step with a "RUN;" statement. The
600 "RUN;" statement is what tells SAS that it should process the preceding
603 @item Graphics (interactive) on the remote machine. If you run X11
604 (@xref{X11}, X-windows)
605 on both the local and remote machines then you should be able to
606 display the graphs locally by setting the @samp{DISPLAY} environment
607 variable appropriately. Windows users can download @samp{xfree86}
610 @item Graphics (static) on the remote machine.
611 If you don't run the X window system on the local machine, then you can write
612 graphics to a file on the remote machine, and display the file in
613 a graphics viewer on the local machine. Most statistical software can
614 write one or more of postscript, GIF, or JPEG files.
615 Depending on the versions of emacs and the operating system that you
616 are running, emacs itself may display @samp{.gif} and @samp{.jpg}
617 files. Otherwise, a graphics file viewer will be needed.
618 Ghostscript/ghostview may be downloaded to display @samp{.ps} and
619 @samp{.eps} files. Viewers for GIF and JPEG are usually included with
620 operating systems. @xref{ESS(SAS)--Function keys for batch processing},
621 for more information on using the F12 key for displaying graphics files
625 Should you or a colleague inadvertently start a statistical process in
626 an ordinary @samp{*shell*} buffer, the @samp{ess-remote} command can
627 be used to convert it to an ESS buffer and allow you to use the ESS
630 We have two older commands, now deprecated, for accessing ESS processes
632 @xref{S+elsewhere and ESS-elsewhere}.
635 @comment node-name, next, previous, up
636 @node S+elsewhere and ESS-elsewhere, Customizing startup, ESS processes on Remote Computers, Interactive ESS
637 @section S+elsewhere and ESS-elsewhere
639 These commands are now deprecated. We recommend @samp{ess-remote}. We
640 have two versions of the elsewhere function. @samp{S+elsewhere} is
641 specific for the S-Plus program. The more general function
642 @samp{ESS-elsewhere} is not as stable.
645 @item Enter @samp{M-x S+elsewhere}.
646 You will be prompted for a starting directory. I usually give it my
647 project directory on the local machine, say @samp{~myname/myproject/}
649 Or enter @samp{M-x ESS-elsewhere}. You will be prompted for an ESS
650 program and for a starting directory. I usually give it my project
651 directory on the local machine, say @samp{~myname/myproject/}
653 @item The @samp{*S+3*} buffer will appear with a prompt from the
654 local operating system (the unix prompt on a unix workstation or with
655 cygwin bash on a PC, or the msdos prompt on a PC without bash). emacs
656 may freeze because the cursor is at the wrong place. Unfreeze it with
657 @samp{C-g} then move the cursor to the end with @samp{M->}.
658 With @samp{S+elsewhere} the buffer name is based on the name of the ESS program.
660 @samp{telnet myname@@other.machine} (or @samp{ssh myname@@other.machine}).
661 You will be prompted for your password on the remote machine.
663 @samp{M-x send-invisible}
664 before typing the password itself.
666 @item Before starting the ESS process, type @samp{stty -echo nl}
667 at the unix prompt. The @samp{-echo} turns off the echo, the
668 @samp{nl} turns off the newline that you see as @samp{^M}.
670 @item You are now talking to the unix prompt on the other machine in the
671 @samp{*S+3*} buffer. cd into the directory for the current project and start
672 the ESS process by entering
673 @samp{Splus} or @samp{R} or @samp{sas -stdio}
674 as appropriate. If you can login remotely to your Windows 2000, then
675 you should be able to run @samp{Sqpe} on the Windows machine. I haven't
676 tested this and noone has reported their tests to me. You will not be
677 able to run the GUI through this text-only connection.
679 @item Once you get the S or R or SAS prompt, then you are completely connected.
680 All the @samp{C-c C-n} and related commands work correctly in sending
681 commands from @samp{myfile.s} or @samp{myfile.r} on the PC to the
682 @samp{*S+3*} buffer running the S or R or SAS program on the remote machine.
684 @item Graphics on the remote machine works fine. If you run the X window
685 system on the remote unix machine you should be able to display them in
686 @samp{xfree86} on your PC. If you don't run X11, then you can write
687 graphics to the postscript device and copy it to your PC with dired and
688 display it with ghostscript.
692 @comment node-name, next, previous, up
693 @node Customizing startup, , S+elsewhere and ESS-elsewhere, Interactive ESS
694 @section Changing the startup actions
696 If you do not wish ESS to prompt for a starting directory when starting
697 a new process, set the variable @code{ess-ask-for-ess-directory} to
698 @vindex ess-ask-for-ess-directory
699 @code{nil}. In this case, the value of the variable @code{ess-directory}
700 @vindex ess-directory
701 is used as the starting directory. The default value for this variable
702 is your home directory. If @code{ess-ask-for-ess-directory} has a
703 non-@code{nil} value (as it does by default) then the value of
704 @code{ess-directory} provides the default when prompting for the
705 starting directory. Incidentally, @code{ess-directory} is an ideal
706 variable to set in @code{ess-pre-run-hook}.
708 If you like to keep a record of your @Sl{} sessions, set the variable
709 @code{ess-ask-about-transfile} to @code{t}, and you will be asked for a
710 filename for the transcript before the ESS process starts.
712 @defvr {User Option} ess-ask-about-transfile
713 If non-@code{nil}, as for a file name in which to save the session
717 @cindex transcript file
718 Enter the name of a file in which to save the transcript at the prompt.
719 If the file doesn't exist it will be created (and you should give it a
720 file name ending in @samp{.St}); if the file already exists the
721 transcript will be appended to the file. (Note: if you don't set this
722 variable but you still want to save the transcript, you can still do it
723 later --- @pxref{Saving transcripts}.)
725 Once these questions are answered (if they are asked at all) the S
726 process itself is started by calling the program name specified in the
727 variable @code{inferior-ess-program}.
728 @vindex inferior-ess-program
729 If you need to pass any arguments to this program, they may be specified
730 in the variable @code{inferior-@var{S_program_name}-args} (e.g. if
731 @code{inferior-ess-program} is @code{"S+"} then the variable to set is
732 @code{inferior-S+-args}.
733 @cindex arguments to S program
734 It is not normally necessary to pass arguments to the @Sl{} program; in
735 particular do not pass the @samp{-e} option to @code{Splus}, since ESS
736 provides its own command history mechanism.
738 By default, the new process will be displayed in the same window in the
739 current frame. If you wish your S process to appear in a separate
740 variable, customize the variable @code{inferior-ess-own-frame}.
741 Alternatively, change @code{inferior-ess-same-window} if you wish the
742 process to appear within another window of the current frame.
744 @comment node-name, next, previous, up
745 @node Entering commands, Transcript Mode, Interactive ESS, Top
746 @chapter Interacting with the ESS process
747 @cindex entering commands
749 @cindex sending input
751 The primary function of the ESS package is to provide an easy-to-use
752 front end to the @Sl{} interpreter. This is achieved by running the S
753 process from within an Emacs buffer, so that the Emacs editing commands
754 are available to correct mistakes in commands, etc. The features of
755 Inferior @Sl{} mode are similar to those provided by the standard Emacs
756 shell mode (@pxref{Shell Mode,,, emacs, The Gnu Emacs Reference
757 Manual}). Command-line completion of @Sl{} objects and a number of `hot
758 keys' for commonly-used @Sl{} commands are also provided for ease of
762 * Command-line editing:: Entering commands and fixing mistakes
763 * Completion:: Completion of object names
764 * Completion details:: Advanced completion concepts
765 * Transcript:: Manipulating the transcript
766 * Command History:: Command History
767 * History expansion:: References to historical commands
768 * Hot keys:: Hot keys for common commands
769 * Statistical Process running in ESS?::
770 * Emacsclient:: Using emacsclient
771 * Other:: Other commands provided by inferior-ESS
774 @comment node-name, next, previous, up
775 @node Command-line editing, Completion, Entering commands, Entering commands
776 @section Entering commands and fixing mistakes
777 @cindex command-line editing
779 Sending a command to the ESS process is as simple as typing it in
780 and pressing the @key{RETURN} key:
784 @kbd{RET} (@code{inferior-ess-send-input}) @*
785 @pindex inferior-ess-send-input
786 Send the command on the current line to the ESS process.
789 If you make a typing error before pressing @kbd{RET} all the usual Emacs
790 editing commands are available to correct it (@pxref{Basic, Basic, Basic
791 editing commands, emacs, The GNU Emacs Reference Manual}). Once the
792 command has been corrected you can press @key{RETURN} (even if the
793 cursor is not at the end of the line) to send the corrected command to
796 ESS provides some other commands which are useful for fixing mistakes:
800 @kbd{C-c C-w} (@code{backward-kill-word}) @*
801 @pindex backward-kill-word
802 Deletes the previous word (such as an object name) on the command line.
805 @kbd{C-c C-u} (@code{comint-kill-input}) @*
806 @pindex comint-kill-input
807 Deletes everything from the prompt to point. Use this to abandon a
808 command you have not yet sent to the ESS process.
811 @kbd{C-c C-a} (@code{comint-bol}) @*
813 Move to the beginning of the line, and then skip forwards past the
817 @xref{Shell Mode,,, emacs, The Gnu Emacs Reference Manual}, for other
818 commands relevant to entering input.
820 @comment node-name, next, previous, up
821 @node Completion, Completion details, Command-line editing, Entering commands
822 @section Completion of object names
823 @cindex completion of object names
824 @cindex command-line completion
826 In the process buffer, the @key{TAB} key is for completion, similar to
827 that provided by Shell Mode for filenames. In Inferior @Sl{} mode,
828 pressing the @key{TAB} key when the cursor is following the first few
829 characters of an object name @emph{completes} the object name; if the
830 cursor is following a file name @kbd{TAB} completes the file name.
834 @kbd{TAB} (@code{comint-dynamic-complete}) @*
835 @pindex comint-dynamic-complete
836 Complete the @Sl{} object name or filename before point.
839 When the cursor is just after a partially-completed object name,
840 pressing @key{TAB} provides completion in a similar fashion to
843 except that completion is performed over all known @Sl{} object names
844 instead of file names. ESS maintains a list of all objects known to S
845 at any given time, which basically consists of all objects (functions
846 and datasets) in every attached directory listed by the @code{search()}
849 along with the component objects of attached data frames
851 (if your version of @Sl{} supports them).
853 For example, consider the three functions (available in Splus version
854 3.0) called @code{binomplot()}, @code{binom.test()} and
855 @code{binomial()}. Typing @kbd{bin TAB} after the @Sl{} prompt will
856 insert the characters @samp{om}, completing the longest prefix
857 (@samp{binom}) which distinguishes these three commands. Pressing
858 @kbd{TAB} once more provides a list of the three commands which have
859 this prefix, allowing you to add more characters (say, @samp{.}) which
860 specify the function you desire. After entering more characters
861 pressing @kbd{TAB} yet again will complete the object name up to
862 uniqueness, etc. If you just wish to see what completions exist without
863 adding any extra characters, type @kbd{M-?}.
867 @kbd{M-?} (@code{ess-list-object-completions}) @*
868 @pindex ess-list-object-completions
869 List all possible completions of the object name at point.
872 ESS also provides completion over the components of named lists accessed
873 using the @samp{$} notation, to any level of nested lists. This feature
874 is particularly useful for checking what components of a list object
875 exist while partway through entering a command: simply type the object
876 name and @samp{$} and press @kbd{TAB} to see the names of existing list
877 components for that object.
878 @cindex lists, completion on
879 @cindex completion on lists
881 @cindex completion on file names
882 Completion is also provided over file names, which is particularly
883 useful when using @Sl{} functions such as @code{get()} or @code{scan()}
884 which require fully expanded file names. Whenever the cursor is within
885 an @Sl{} string, pressing @kbd{TAB} completes the file name before
886 point, and also expands any @samp{~} or environment variable references.
888 If the cursor is not in a string and does not follow a (partial) object
889 name, the @key{TAB} key has a third use: it expands history references.
890 @xref{History expansion}.
892 @comment node-name, next, previous, up
893 @node Completion details, Transcript, Completion, Entering commands
894 @section Completion details
896 ESS automatically keeps track of any objects added or deleted to the
897 system (such as new objects created, or directories added to the search
898 list) to make completion as accurate as possible. Whenever ESS notices
899 that search list has changed
900 @vindex ess-change-sp-regexp
901 @footnote{The variable @code{ess-change-sp-regexp} is a regular
902 expression matching commands which change the search list. You will
903 need to modify this variable if you have defined custom commands (other
904 than @code{attach}, @code{detach}, @code{collection} or @code{library})
905 which modify the search list.} when you attach a directory or data
906 frame, the objects associated with it immediately become available for a
907 completion; when it is detached completion is no longer available on
910 To maintain a list of accessible objects for completion, ESS needs to
911 determine which objects are contained in each directory or data frame on
912 the search list. This is done at the start of each @Sl{} session, by
913 running the @code{objects()} command on every element of the search
916 @c On some systems, however, this can be rather slow; it's doubly
917 @c frustrating when you consider that most of the directories on the search
918 @c list are the standard @Sl{} libraries, which never change anyway! When
919 @c ESS was installed, a database of the standard object names should have
920 @c been created which should speed up this process at the start of an S
921 @c session; if it has not been created you will get a warning like
922 @c `S-namedb.el does not exist'. @xref{Installation}, for information on
923 @c how to create this database.
925 Efficiency in completion is gained by maintaining a cache of objects
926 currently known to S; when a new object becomes available or is deleted,
927 only one component of the cache corresponding to the associated
928 directory needs to be refreshed. If ESS ever becomes confused about
929 what objects are available for completion (such as when if refuses to
930 complete an object you @strong{know} is there), the command @kbd{M-x
933 forces the @emph{entire} cache to be refreshed, which should fix the
936 @comment node-name, next, previous, up
937 @node Transcript, Command History, Completion details, Entering commands
938 @section Manipulating the transcript
940 Most of the time, the cursor spends most of its time at the bottom of
941 the ESS process buffer, entering commands. However all the input
942 and output from the current (and previous) ESS sessions is stored in
943 the process buffer (we call this the transcript) and often we want to
945 move back up through the buffer, to look at the output from previous
946 commands for example.
948 Within the process buffer, a paragraph
949 @cindex paragraphs in the process buffer
950 is defined as the prompt, the command after the prompt, and the output
951 from the command. Thus @kbd{M-@{} and @kbd{M-@}} move you backwards and
952 forwards, respectively, through commands in the transcript. A
953 particularly useful command is @kbd{M-h} (@code{mark-paragraph}) which
954 will allow you to mark a command and its entire output (for deletion,
955 perhaps). For more information about paragraph commands,
956 @pxref{Paragraphs, Paragraphs, Paragraphs, emacs, The GNU Emacs
959 If an ESS process finishes and you restart it in the same process
960 buffer, the output from the new ESS process appears after the output
961 from the first ESS process separated by a form-feed (@samp{^L})
962 character. Thus pages in the ESS
963 @cindex pages in the process buffer
964 process buffer correspond to ESS sessions. Thus, for example, you may
965 use @kbd{C-x [} and @kbd{C-x ]} to move backward and forwards through
966 ESS sessions in a single ESS process buffer. For more information about
967 page commands, @pxref{Pages, Pages, Pages, emacs, The GNU Emacs
971 * Last command:: Manipulating the output from the last command
972 * Process buffer motion:: Viewing older commands
973 * Transcript resubmit:: Re-submitting commands from the transcript
974 * Saving transcripts:: Keeping a record of your S session
977 @comment node-name, next, previous, up
978 @node Last command, Process buffer motion, Transcript, Transcript
979 @subsection Manipulating the output from the last command
981 Viewing the output of the command you have just entered is a common
982 occurrence and ESS provides a number of facilities for doing this.
983 @c Within the ESS process buffer, the variable @code{scroll-step}
984 @c @vindex scroll-step
985 @c is set to 4 (you can redefine this using @code{inferior-ess-mode-hook}
986 @c @vindex inferior-ess-hook
987 @c if you wish - @pxref{Hooks},) so that the cursor is usually near the
988 @c bottom of the window.
989 Whenever a command produces a longish output, it is possible that the
990 window will scroll, leaving the next prompt near the middle of the
991 window. The first part of the command output may have scrolled off the
992 top of the window, even though the entire output would fit in the window
993 if the prompt were near the bottom of the window. If this happens, you
998 @kbd{C-c C-e} (@code{comint-show-maximum-output}) @*
999 @pindex comint-show-maximum-output
1000 Move to the end of the buffer, and place cursor on bottom line of
1005 to make more of the last output visible. (To make this happen
1006 automatically for all inputs, set the variable
1007 @code{comint-scroll-to-bottom-on-input} to @code{t}.)
1009 If the first part of the output is still obscured, use
1010 @cindex reading long command outputs
1013 @kbd{C-c C-r} (@code{comint-show-output}) @*
1014 @pindex comint-show-output
1015 Moves cursor to the previous command line and and places it at the top
1020 to view it. Finally, if you want to discard the last command output
1025 @kbd{C-c C-o} (@code{comint-kill-output}) @*
1026 @pindex comint-kill-output
1027 @cindex deleting output
1028 Deletes everything from the last command to the current prompt.
1032 to delete it. Use this command judiciously to keep your transcript to a
1033 more manageable size.
1035 @comment node-name, next, previous, up
1036 @node Process buffer motion, Transcript resubmit, Last command, Transcript
1037 @subsection Viewing older commands
1039 If you want to view the output from more historic commands than the
1040 previous command, commands are also provided to move backwards and
1041 forwards through previously entered commands in the process buffer:
1045 @kbd{C-c C-p} (@code{comint-previous-input}) @*
1046 @pindex comint-previous-input
1047 Moves point to the preceding command in the process buffer.
1050 @kbd{C-c C-n} (@code{comint-next-input}) @*
1051 @pindex comint-next-input
1052 Moves point to the next command in the process buffer.
1056 Note that these two commands are analogous to @kbd{C-p} and @kbd{C-n}
1057 but apply to command lines rather than text lines. And just like
1058 @kbd{C-p} and @kbd{C-n}, passing a prefix argument to these commands
1059 means to move to the @var{ARG}'th next (or previous) command. (These
1060 commands are also discussed in @ref{Shell History Copying,,Shell History
1061 Copying,emacs, The GNU Emacs Reference Manual}.)
1063 There are also two similar commands (not bound to any keys by default)
1064 which move to preceding or succeeding commands, but which first prompt
1065 for a regular expression (@pxref{Regexps,,Syntax of Regular
1066 Expression,emacs, The GNU Emacs Reference Manual}), and then moves to
1067 the next (previous) command matching the pattern.
1071 @code{(comint-backward-matching-input regexp arg)} @*
1072 @pindex comint-backward-matching-input
1073 @code{(comint-forward-matching-input regexp arg)} @*
1074 @pindex comint-forward-matching-input
1075 Search backward (forward) through the transcript buffer for the
1076 @var{arg}'th previous (next) command matching @var{regexp}. @var{arg}
1077 is the prefix argument; @var{regexp} is prompted for in the minibuffer.
1080 @comment node-name, next, previous, up
1081 @node Transcript resubmit, Saving transcripts, Process buffer motion, Transcript
1082 @subsection Re-submitting commands from the transcript
1084 When moving through the transcript, you may wish to re-execute some of
1085 the commands you find there. ESS provides three commands to do this;
1086 these commands may be used whenever the cursor is within a command line
1087 in the transcript (if the cursor is within some command @emph{output},
1088 an error is signalled). Note all three commands involve the @key{RETURN}
1093 @kbd{RET} (@code{inferior-ess-send-input}) @*
1094 @pindex inferior-ess-send-input
1095 Copy the command under the cursor to the current command line, and
1099 @kbd{C-c RET} (@code{comint-copy-old-input}) @*
1100 @pindex comint-copy-old-input
1101 Copy the command under the cursor to the current command line, but don't
1102 execute it. Leaves the cursor on the command line so that the copied
1103 command may be edited.
1106 @kbd{M-RET} (@code{ess-transcript-send-command-and-move}) @*
1107 @pindex ess-transcript-send-command-and-move
1108 Copy the command under the cursor to the current command line, and
1109 execute it. Moves the cursor to the following command.
1112 When the cursor is not after the current prompt, the @key{RETURN} key
1113 has a slightly different behavior than usual. Pressing @kbd{RET} on any
1114 line containing a command that you entered (i.e. a line beginning with a
1115 prompt) sends that command to the ESS process once again. If you
1116 wish to edit the command before executing it, use @kbd{C-c RET} instead;
1117 it copies the command to the current prompt but does not execute it,
1118 allowing you to edit it before submitting it.
1120 These two commands leave the cursor at the new command line, allowing
1121 you to continue with interactive use of S. If you wish to resubmit a
1122 series of commands from the transcript, consider using @kbd{M-RET}
1123 instead, which leaves the cursor at the command line following the one
1124 you re-submitted. Thus by using @kbd{M-RET} repeatedly, you can
1125 re-submit a whole series of commands.
1127 These commands work even if if the current line is a continuation line
1128 (i.e. the prompt is @samp{+} instead of @samp{>}) --- in this case all
1129 the lines that form the multi-line command are concatenated together and
1130 the resulting command is sent to the ESS process (currently this is
1131 the only way to resubmit a multi-line command to the ESS process in
1132 one go). If the current line does
1133 @cindex multi-line commands, resubmitting
1134 not begin with a prompt, an error is signalled. This feature, coupled
1135 with the command-based motion commands described above, could be used as
1136 a primitive history mechanism. ESS provides a more sophisticated
1137 mechanism, however, which is described in @ref{Command History}.
1139 @comment node-name, next, previous, up
1140 @node Saving transcripts, , Transcript resubmit, Transcript
1141 @subsection Keeping a record of your S session
1143 To keep a record of your @Sl{} session in a disk file, use the Emacs
1144 command @kbd{C-x C-w} (@code{write-file}) to attach a file to the
1145 ESS process buffer. The name of the process buffer will (probably)
1146 change to the name of the file, but this is not a problem. You can
1147 still use @Sl{} as usual; just remember to save the file before you quit
1148 Emacs with @kbd{C-x C-s}. You can make ESS prompt you for a filename in
1149 which to save the transcript every time you start @Sl{} by setting the
1151 @vindex ess-ask-about-transfile
1152 @code{ess-ask-about-transfile} to @code{t}; see @ref{Customizing startup}.
1153 @cindex transcript file names
1154 We recommend you save your transcripts with filenames that end in
1155 @samp{.St}. There is a special mode (ESS transcript mode ---
1156 @pxref{Transcript Mode}) for editing transcript files which is
1157 automatically selected for files with this suffix.
1159 @cindex editing transcripts
1160 S transcripts can get very large, so some judicious editing is
1161 appropriate if you are saving it in a file. Use @kbd{C-c C-o} whenever
1162 a command produces excessively long output (printing large arrays, for
1163 example). Delete erroneous commands (and the resulting error messages
1164 or other output) by moving to the command (or its output) and typing
1165 @kbd{M-h C-w}. Also, remember that @kbd{C-c C-e} (and other hot keys)
1166 may be used for commands whose output you do not wish to appear in the
1167 transcript. These suggestions are appropriate even if you are not
1168 saving your transcript to disk, since the larger the transcript, the
1169 more memory your Emacs process will use on the host machine.
1171 Finally, if you intend to produce @Sl{} source code (suitable for using
1172 with @code{source()} or inclusion in an @Sl{} function) from a
1173 transcript, then the command @kbd{M-x ess-transcript-clean-region} may
1175 @pindex ess-transcript-clean-region
1176 This command works in any Emacs buffer, and removes all prompts and
1177 command output from an ESS transcript within the current region, leaving
1178 only the commands. Don't forget to remove any erroneous commands first!
1180 @comment node-name, next, previous, up
1181 @node Command History, History expansion, Transcript, Entering commands
1182 @section Command History
1183 @cindex command history
1184 @cindex editing commands
1185 @cindex re-executing commands
1187 ESS provides easy-to-use facilities for re-executing or editing previous
1188 commands. An input history of the last few commands is maintained (by
1189 default the last 50 commands are stored, although this can be changed by
1190 setting the variable @code{comint-input-ring-size} in
1191 @vindex comint-input-ring-size
1192 @code{inferior-ess-mode-hook}.) The simplest history commands simply
1193 select the next and previous commands in the input history:
1197 @kbd{M-p} (@code{comint-previous-input}) @*
1198 @pindex comint-previous-input
1199 Select the previous command in the input history.
1202 @kbd{M-n} (@code{comint-next-input}) @*
1203 @pindex comint-next-input
1204 Select the next command in the input history.
1208 For example, pressing @kbd{M-p} once will re-enter the last command into
1209 the process buffer after the prompt but does not send it to the ESS
1210 process, thus allowing editing or correction of the command before the
1211 ESS process sees it. Once corrections have been made, press
1212 @kbd{RET} to send the edited command to the ESS process.
1214 If you want to select a particular command from the history by matching
1215 it against a regular expression (@pxref{Regexps,,Syntax of Regular
1216 Expression,emacs, The GNU Emacs Reference Manual}), to search for a
1217 particular variable name for example, these commands are also available:
1221 @kbd{M-r} (@code{comint-previous-matching-input}) @*
1222 @pindex comint-previous-matching-input
1223 Prompt for a regular expression, and search backwards through the input
1224 history for a command matching the expression.
1227 @kbd{M-s} (@code{comint-next-matching-input}) @*
1228 @pindex comint-next-matching-input
1229 Prompt for a regular expression, and search backwards through the input
1230 history for a command matching the expression.
1234 A common type of search is to find the last command that began with a
1235 particular sequence of characters; the following two commands provide an
1236 easy way to do this:
1240 @kbd{A-M-r} (@code{comint-previous-matching-input-from-input}) @*
1241 @pindex comint-previous-matching-input-from-input
1242 Select the previous command in the history which matches the string
1246 @kbd{A-M-s} (@code{comint-next-matching-input-from-input}) @*
1247 @pindex comint-next-matching-input-from-input
1248 Select the next command in the history which matches the string typed so
1253 Instead of prompting for a regular expression to match against, as they
1254 instead select commands starting with those characters already entered.
1255 For instance, if you wanted to re-execute the last @code{attach()}
1256 command, you may only need to type @kbd{att} and then @kbd{A-M-r} and
1257 @kbd{RET}. (Note: you may not have an @key{ALT} key on your keyboard,
1258 in which case it may be a good idea to bind these commands to some other
1261 @xref{Shell Ring,,Shell History Ring,emacs, The GNU Emacs Reference
1262 Manual}, for a more detailed discussion of the history mechanism.
1264 @comment node-name, next, previous, up
1265 @node History expansion, Hot keys, Command History, Entering commands
1266 @section References to historical commands
1268 Instead of searching through the command history using the command
1269 described in the previous section, you can alternatively refer to a
1270 historical command directly using a notation very similar to that used
1271 in @code{csh}. History references are introduced by a @samp{!} or
1272 @samp{^} character and have meanings as follows:
1276 The immediately previous command
1279 The @var{N}th previous command
1282 The last command beginning with the string @samp{text}
1285 The last command containing the string @samp{text}
1288 In addition, you may follow the reference with a @dfn{word designator}
1289 to select particular @dfn{words} of the input. A word is defined as a
1290 sequence of characters separated by whitespace. (You can modify this
1291 definition by setting the value of @code{comint-delimiter-argument-list}
1292 to a list of characters that are allowed to separate words and
1293 @vindex comint-delimiter-argument-list
1294 themselves form words.) Words are numbered beginning with zero. The
1295 word designator usually begins with a @samp{:} (colon) character;
1296 however it may be omitted if the word reference begins with a @samp{^},
1297 @samp{$}, @samp{*} or @samp{-}. If the word is to be selected from the
1298 previous command, the second @samp{!} character can be omitted from the
1299 event specification. For instance, @samp{!!:1} and @samp{!:1} both
1300 refer to the first word of the previous command, while @samp{!!$} and
1301 @samp{!$} both refer to the last word in the previous command. The
1302 format of word designators is as follows:
1306 The zeroth word (i.e. the first one on the command line)
1309 The @var{n}th word, where @var{n} is a number
1312 The first word (i.e. the second one on the command line)
1317 @item @var{x}-@var{y}
1318 A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}
1321 All the words except the zeroth word, or nothing if the command had just
1322 one word (the zeroth)
1325 Abbreviates @var{x}-$
1328 Like @samp{@var{x}*}, but omitting the last word
1331 In addition, you may surround the entire reference except for the first
1332 @samp{!} by braces to allow it to be followed by other (non-whitespace)
1333 characters (which will be appended to the expanded reference).
1335 Finally, ESS also provides quick substitution; a reference like
1336 @samp{^old^new^} means ``the last command, but with the first occurrence
1337 of the string @samp{old} replaced with the string @samp{new}'' (the last
1338 @samp{^} is optional). Similarly, @samp{^old^} means ``the last
1339 command, with the first occurrence of the string @samp{old} deleted''
1340 (again, the last @samp{^} is optional).
1342 To convert a history reference as described above to an input suitable
1343 for S, you need to @dfn{expand} the history reference, using the
1344 @key{TAB} key. For this to work, the cursor must be preceded by a space
1345 (otherwise it would try to complete an object name) and not be within a
1346 string (otherwise it would try to complete a filename). So to expand
1347 the history reference, type @kbd{SPC TAB}. This will convert the
1348 history reference into an @Sl{} command from the history, which you can
1349 then edit or press @key{RET} to execute.
1351 For example, to execute the last command that referenced the variable
1352 @code{data}, type @kbd{!?data SPC TAB RET}.
1354 @comment node-name, next, previous, up
1355 @node Hot keys, Statistical Process running in ESS?, History expansion, Entering commands
1356 @section Hot keys for common commands
1358 ESS provides a number of commands for executing the commonly used
1359 functions. These commands below are basically information-gaining
1360 commands (such as @code{objects()} or @code{search()}) which tend to
1361 clutter up your transcript and for this reason some of the hot keys
1362 display their output in a temporary buffer instead of the process buffer
1363 by default. This behavior is controlled by the variable
1364 @code{ess-execute-in-process-buffer} which, if
1365 @vindex ess-execute-in-process-buffer
1366 non-@code{nil}, means that these commands will produce their output in
1367 the process buffer instead. In any case, passing a prefix argument to
1368 the commands (with @kbd{C-u}) will reverse the meaning of
1369 @code{ess-execute-in-process-buffer} for that command, i.e. the output
1370 will be displayed in the process buffer if it usually goes to a
1371 temporary buffer, and vice-versa. These are the hot keys that behave in
1376 @kbd{C-c C-x} (@code{ess-execute-objects}) @*
1377 @pindex ess-execute-objects
1378 Sends the @code{objects()}
1380 command to the ESS process. A prefix argument specifies the
1381 position on the search list (use a negative argument to toggle
1382 @code{ess-execute-in-process-buffer} as well). A quick way to see what
1383 objects are in your working directory.
1388 @kbd{C-c C-s} (@code{ess-execute-search}) @*
1389 @pindex ess-execute-search
1390 Sends the @code{search()}
1392 command to the ESS process.
1397 @kbd{C-c C-e} (@code{ess-execute}) @*
1399 Prompt for an ESS expression, and evaluate it.
1402 @code{ess-execute} may seem pointless when you could just type the
1403 command in anyway, but it proves useful for `spot' calculations which
1404 would otherwise clutter your transcript, or for evaluating an expression
1405 while partway through entering a command. You can also use this command
1406 to generate new hot keys using the Emacs keyboard macro facilities;
1407 @pxref{Keyboard Macros, Keyboard Macros, Keyboard Macros, emacs, The GNU
1408 Emacs Reference Manual}.
1410 @cindex keyboard short cuts
1412 The following hot keys do not use @code{ess-execute-in-process-buffer}
1413 to decide where to display the output --- they either always display in
1414 the process buffer or in a separate buffer, as indicated:
1418 @kbd{C-c C-a} (@code{ess-execute-attach}) @*
1419 @pindex ess-execute-attach
1420 Prompts for a directory to attach to the ESS process with the
1421 @code{attach()} command.
1423 If a numeric prefix argument is given it is used as the position on the
1424 search list to attach the directory; otherwise the @Sl{} default of 2 is
1425 used. The @code{attach()} command actually executed appears in the
1429 @kbd{C-c C-l} (@code{ess-load-file}) @*
1430 @pindex ess-load-file
1431 Prompts for a file to load into the ESS process using
1432 @code{source()}. If there is an error during loading, you can jump to
1433 the error in the file with @kbd{C-x `} (@code{ess-parse-errors}).
1434 @pindex ess-parse-errors
1435 @xref{Error Checking}, for more details.
1438 @kbd{C-c C-v} (@code{ess-display-help-on-object}) @* Pops up a help
1439 buffer for an @Sl{} object or function. See @ref{Help} for more
1443 @kbd{C-c C-q} (@code{ess-quit}) @*
1444 @cindex quitting from ESS
1445 @cindex killing the ESS process
1446 Sends the @code{q()}
1448 command to the ESS process (or @code{(exit)}
1450 to the @b{XLS} process), and cleans up any temporary buffers (such as
1451 help buffers or edit buffers) you may have created along the way. Use
1452 this command when you have finished your @Sl{} session instead of simply
1453 typing @code{q()} yourself, otherwise you will need to issue the command
1454 @kbd{M-x ess-cleanup}
1457 @cindex temporary buffers, killing
1458 @cindex killing temporary buffers
1459 command explicitly to make sure that all the files that need to be saved
1460 have been saved, and that all the temporary buffers have been killed.
1463 @comment node-name, next, previous, up
1464 @node Statistical Process running in ESS?, Emacsclient, Hot keys, Entering commands
1465 @section Is the Statistical Process running under ESS?
1469 For the S languages (S, S-Plus, R) ESS sets an option in the current
1470 process that programs in the language can check to determine the
1471 environment in which they are currently running.
1474 @code{options(STERM="iESS")} for S language processes running in an
1475 inferior @code{@iESS{[S]}} or @code{@iESS{[R]}} buffer.
1478 @code{options(STERM="ddeESS")} for independent S-Plus for Windows
1479 processes running in the GUI and communicating with ESS via
1480 the DDE (Microsoft Dynamic Data Exchange) protocol through a
1481 @code{ddeESS[S]} buffer.
1483 Other values of @code{options()$STERM} that we recommend are:
1486 @item @code{length}: Fixed length xterm or telnet window.
1487 @item @code{scrollable}: Unlimited length xterm or telnet window.
1488 @item @code{server}: S-Plus Stat Server.
1489 @item @code{BATCH}: BATCH.
1490 @item @code{Rgui}: R GUI.
1491 @item @code{Commands}: S-Plus GUI without DDE interface to ESS.
1494 Additional values may be recommended in the future as new interaction
1495 protocols are created. Unlike the values @code{iESS} and @code{ddeESS},
1496 ESS can't set these other values since the S language program is not
1497 under the control of ESS.
1499 @comment node-name, next, previous, up
1500 @node Emacsclient, Other, Statistical Process running in ESS?, Entering commands
1501 @section Using emacsclient
1505 When starting R or S under Unix, ESS sets
1506 @code{options(editor="emacsclient")}. (Under Microsoft Windows, it will
1507 use gnuclient.exe rather than emacsclient, but the same principle
1508 applies.) Within your R session, for example, if you have a function
1509 called @code{iterator}, typing @code{fix(iterator)}, will show that
1510 function in a temporary Emacs buffer. You can then correct the
1511 function. When you kill the buffer, the definition of the function is
1512 updated. Using @code{edit()} rather than @code{fix()} means that the
1513 function is not updated. Finally, the S function @code{page(x)} will
1514 also show a text representation of the object @code{x} in a temporary
1518 @comment node-name, next, previous, up
1519 @node Other, , Emacsclient, Entering commands
1520 @section Other commands provided by inferior-ESS
1522 The following commands are also provided in the process buffer:
1526 @kbd{C-c C-c} (@code{comint-interrupt-subjob}) @*
1527 @pindex comint-interrupt-subjob
1528 Sends a Control-C signal to the ESS process. This has the effect of
1529 @cindex aborting S commands
1530 @cindex interrupting S commands
1531 aborting the current command.
1534 @kbd{C-c C-z} (@code{ess-abort}) @*
1536 @pindex comint-stop-subjob
1537 Sends a STOP signal to the ESS process, killing it immediately.
1538 It's not a good idea to use this, in general: Neither @code{q()} nor
1539 @code{.Last} will be executed and device drivers will not finish
1540 cleanly. This command is provided as a safety to
1541 @code{comint-stop-subjob}, which is usually bound to @kbd{C-c C-z}. If
1542 you want to quit from S, use @kbd{C-c C-q} (@code{ess-quit}) instead.
1544 @cindex aborting the ESS process
1547 @kbd{C-c C-d} (@code{ess-dump-object-into-edit-buffer}) @*
1548 @pindex ess-dump-object-into-edit-buffer
1549 Prompts for an object to be edited in an edit buffer. @xref{Editing}.
1552 Other commands available in Inferior @Sl{} mode are discussed in
1553 @ref{Shell Mode,,, emacs, The Gnu Emacs Reference Manual}.
1555 @comment node-name, next, previous, up
1556 @node Transcript Mode, ESS for the S family, Entering commands, Top
1557 @chapter Manipulating saved transcript files
1559 Inferior @Sl{} mode records the transcript (the list of all commands
1560 executed, and their output) in the process buffer, which can be saved as
1561 a @dfn{transcript file}, which should normally have the suffix
1562 @file{.St}. The most obvious use for a transcript file is as a static
1563 record of the actions you have performed in a particular @Sl{} session.
1564 Sometimes, however, you may wish to re-execute commands recorded in the
1565 transcript file by submitting them to a running ESS process. This
1566 is what Transcript Mode is for.
1568 If you load file a with the suffix @file{.St} into Emacs, it is placed
1569 in S Transcript Mode. Transcript Mode is similar to Inferior @Sl{} mode
1570 (@pxref{Entering commands}):
1571 @cindex transcript mode motion
1572 @cindex motion in transcript mode
1573 paragraphs are defined as a command and its output, and you can move
1574 though commands either with the paragraph commands or with @kbd{C-c C-p}
1578 * Resubmit:: Resubmitting commands from the transcript file
1579 * Clean:: Cleaning transcript files
1582 @comment node-name, next, previous, up
1583 @node Resubmit, Clean, Transcript Mode, Transcript Mode
1584 @section Resubmitting commands from the transcript file
1586 Three commands are provided to re-submit command lines from the
1587 transcript file to a running ESS process. They are:
1591 @kbd{RET} (@code{ess-transcript-send-command}) @*
1592 Send the current command line to the ESS process, and execute it.
1593 @pindex ess-transcript-send-command
1596 @kbd{C-c RET} (@code{ess-transcript-copy-command}) @*
1597 Copy the current command to the ESS process, and switch to the
1598 ESS process buffer (ready to edit the copied command).
1599 @pindex ess-transcript-copy-command
1602 @kbd{M-RET} (@code{ess-transcript-send-command-and-move}) @*
1603 Send the current command to the ESS process, and move to the next
1604 command line. This command is useful for submitting a series of
1609 Note that these commands are similar to those on the same keys in
1610 Inferior @Sl{} Mode. In all three cases, the commands should be
1611 executed when the cursor is on a command line in the transcript; the
1612 prompt is automatically removed before the command is submitted.
1614 @comment node-name, next, previous, up
1615 @node Clean, , Resubmit, Transcript Mode
1616 @section Cleaning transcript files
1618 Yet another use for transcript files is to extract the command lines for
1619 inclusion in an @Sl{} source file or function. Transcript mode provides
1620 one command which does just this:
1624 @kbd{C-c C-w} (@code{ess-transcript-clean-region}) @*
1625 Deletes all prompts and command output in the region, leaving only the
1626 commands themselves.
1630 The remaining command lines may then be copied to a source file or edit
1631 buffer for inclusion in a function definition, or may be evaluated
1632 directly (@pxref{Evaluating code}) using the code evaluation commands
1633 from @Sl{} mode, also available in @Sl{} Transcript Mode.
1636 @comment node-name, next, previous, up
1637 @node ESS for the S family, Editing, Transcript Mode, Top
1638 @chapter ESS for the S family
1640 * ESS(S)--Editing files::
1641 * iESS(S)--Inferior ESS processes::
1642 * ESS-help--assistance with viewing help::
1643 * Philosophies for using ESS(S)::
1644 * Scenarios for use (possibilities--based on actual usage)::
1645 * Customization Examples and Solutions to Problems::
1647 @include help-s.texi
1649 @comment node-name, next, previous, up
1650 @node Editing, Editing R documentation files, ESS for the S family, Top
1651 @chapter Editing S functions
1653 @cindex editing functions
1654 ESS provides facilities for editing @Sl{} objects within your Emacs
1655 session. Most editing is performed on @Sl{} functions, although in
1656 theory you may edit datasets as well. Edit buffers are always
1657 associated with files, although you may choose to make these files
1658 temporary if you wish. Alternatively, you may make use of a simple yet
1659 powerful mechanism for maintaining backups of text representations of
1660 @Sl{} functions. Error-checking is performed when @Sl{} code is loaded
1661 into the ESS process.
1664 * Edit buffer:: Edit objects in a specialized buffer
1665 * Loading:: Loading source files into the ESS process
1666 * Error Checking:: Detecting errors in source files
1667 * Evaluating code:: Sending code to the ESS process
1668 * Indenting:: Indenting and formatting S code
1669 * Other edit buffer commands:: Commands for motion, completion and more
1670 * Source Files:: Maintaining @Sl{} source files
1671 * Source Directories:: Names and locations of dump files
1674 @comment node-name, next, previous, up
1675 @node Edit buffer, Loading, Editing, Editing
1676 @section Creating or modifying S objects
1679 To edit an @Sl{} object, type
1683 @kbd{C-c C-d} (@code{ess-dump-object-into-edit-buffer}) @*
1684 @pindex ess-dump-object-into-edit-buffer
1685 Edit an @Sl{} object in its own edit buffer.
1688 from within the ESS process buffer (@code{*S*}). You will then be
1689 prompted for an object to edit: you may either type in the name of an
1690 existing object (for which completion is available using the @kbd{TAB}
1692 @cindex completion, when prompted for object names
1693 or you may enter the name of a new object.
1694 @cindex creating new objects
1695 @cindex new objects, creating
1696 A buffer will be created containing the text representation of the
1697 requested object or, if you entered the name of a non-existent object at
1698 the prompt and the variable @code{ess-function-template}
1699 @vindex ess-function-template
1700 is non-@code{nil}, you will be presented with a template defined by that
1701 variable, which defaults to a skeleton function construct.
1703 You may then edit the function as required. The edit buffer generated
1704 by @code{ess-dump-object-into-edit-buffer} is placed in the @code{ESS}
1705 major mode which provides a number of commands to facilitate editing
1706 @Sl{} source code. Commands are provided to intelligently indent @Sl{}
1707 code, evaluate portions of @Sl{} code and to move around @Sl{} code
1711 @cindex reverting function definitions
1712 Note: when you dump a file with @kbd{C-c C-d}, ESS first checks
1713 to see whether there already exists an edit buffer containing that
1714 object and, if so, pops you directly to that buffer. If not, ESS next
1715 checks whether there is a file in the appropriate place with the
1716 appropriate name (@pxref{Source Files}) and if so, reads in that file.
1717 You can use this facility to return to an object you were editing in a
1718 previous session (and which possibly was never loaded to the @Sl{}
1719 session). Finally, if both these tests fail, the ESS process is
1720 consulted and a @code{dump()} command issued.
1722 If you want to force ESS to ask the ESS process for the object's
1723 definition (say, to reformat an unmodified buffer or to revert back to
1724 S's idea of the object's definition) pass a prefix argument to
1725 @code{ess-dump-object-into-edit-buffer} by typing @kbd{C-u C-c C-d}.
1727 @comment node-name, next, previous, up
1728 @node Loading, Error Checking, Edit buffer, Editing
1729 @section Loading source files into the ESS process
1731 The best way to get information --- particularly function definitions
1732 --- into @Sl{} is to load them in as source file, using S's
1733 @code{source} function. You have already seen how to create source
1734 files using @kbd{C-c C-d}; ESS provides a complementary command for
1735 loading source files (even files not created with ESS!) into the ESS
1740 @kbd{C-c C-l} (@code{ess-load-file}) @*
1741 @pindex ess-load-file
1742 Loads a file into the ESS process using @code{source()}.
1747 After typing @kbd{C-c C-l} you will prompted for the name of the file to
1748 load into S; usually this is the current buffer's file which is the
1749 default value (selected by simply pressing @kbd{RET} at the prompt).
1750 You will be asked to save the buffer first if it has been modified (this
1751 happens automatically if the buffer was generated with @kbd{C-c C-d}).
1752 The file will then be loaded, and if it loads successfully you will be
1753 returned to the ESS process.
1755 @comment node-name, next, previous, up
1756 @node Error Checking, Evaluating code, Loading, Editing
1757 @section Detecting errors in source files
1759 @cindex parsing errors
1760 If any errors occur when loading a file with @code{C-c C-l}, ESS will
1761 inform you of this fact. In this case, you can jump directly to the
1762 line in the source file which caused the error by typing @kbd{C-c `}
1763 (@code{ess-parse-errors}).
1764 @pindex ess-parse-errors
1765 You will be returned to the offending file (loading it into a buffer if
1766 necessary) with point at the line @Sl{} reported as containing the
1767 error. You may then correct the error, and reload the file. Note that
1768 none of the commands in an @Sl{} source file will take effect if any
1769 part of the file contains errors.
1771 Sometimes the error is not caused by a syntax error (loading a
1772 non-existent file for example). In this case typing @kbd{C-c `} will
1773 simply display a buffer containing S's error message. You can force
1774 this behavior (and avoid jumping to the file when there @emph{is} a
1775 syntax error) by passing a prefix argument to @code{ess-parse-errors}
1776 with @kbd{C-u C-c `}.
1778 @comment node-name, next, previous, up
1779 @node Evaluating code, Indenting, Error Checking, Editing
1780 @section Sending code to the ESS process
1782 Other commands are also available for evaluating portions of code in the
1783 S process. These commands cause the selected code to be evaluated
1784 directly by the ESS process as if you had typed them in at the
1785 command line; the @code{source()} function is not used. You may choose
1786 whether both the commands and their output appear in the process buffer
1787 (as if you had typed in the commands yourself) or if the output alone is
1788 echoed. The behavior is controlled by the variable
1789 @code{ess-eval-visibly-p} whose default is @code{nil}
1790 @vindex ess-eval-visibly-p
1791 (display output only). Passing a prefix argument (@kbd{C-u}) to any of
1792 the following commands, however, reverses the meaning of
1793 @code{ess-eval-visibly-p} for that command only --- for example @kbd{C-u
1794 C-c C-j} echoes the current line of S (or other) code in the ESS
1795 process buffer, followed by its output. This method of evaluation is an
1796 alternative to S's @code{source()} function
1798 @cindex echoing commands when evaluating
1799 @cindex evaluating code with echoed commands
1800 when you want the input as well as the output to be displayed. (You can
1801 sort of do this with @code{source()} when the option @code{echo=T} is
1802 set, except that prompts do not get displayed. ESS puts prompts in the
1803 right places.) The commands for evaluating code are:
1806 @cindex evaluating S expressions
1808 @kbd{C-c C-j} (@code{ess-eval-line}) @*
1809 @pindex ess-eval-line
1810 Send the line containing point to the ESS process.
1813 @kbd{C-c M-j} (@code{ess-eval-line-and-go}) @*
1814 @pindex ess-eval-line-and-go
1815 As above, but returns you to the ESS process buffer as well.
1818 @kbd{C-c C-f} or @kbd{ESC C-x} (aka @kbd{M-C-x}) (@code{ess-eval-function}) @*
1819 @pindex ess-eval-function
1820 Send the @Sl{} function containing point to the ESS process.
1823 @kbd{C-c M-f} (@code{ess-eval-function-and-go}) @*
1824 @pindex ess-eval-function-and-go
1825 As above, but returns you to the ESS process buffer as well.
1828 @kbd{C-c C-r} (@code{ess-eval-region}) @*
1829 @pindex ess-eval-region
1830 Send the text between point and mark to the ESS process.
1833 @kbd{C-c M-r} (@code{ess-eval-region-and-go}) @*
1834 @pindex ess-eval-region-and-go
1835 As above, but returns you to the ESS process buffer as well.
1838 @kbd{C-c C-b} (@code{ess-eval-buffer}) @*
1839 @pindex ess-eval-buffer
1840 Send the contents of the edit buffer to the ESS process.
1843 @kbd{C-c M-b} (@code{ess-eval-buffer-and-go}) @*
1844 @pindex ess-eval-function-and-go
1845 As above, but returns you to the ESS process buffer as well.
1848 @kbd{C-c C-n} (@code{ess-eval-line-and-step}) @*
1849 @pindex ess-eval-line-and-step
1850 @cindex stepping through code
1851 @cindex debugging S functions
1852 Sends the current line to the ESS process, echoing it in the process
1853 buffer, and moves point to the next line. Useful when debugging for
1854 stepping through your code.
1857 It should be stressed once again that these @code{ess-eval-} commands
1858 should only be used for evaluating small portions of code for debugging
1859 purposes, or for generating transcripts from source files. When editing
1860 S functions, @kbd{C-c C-l} is the command to use to update the
1861 function's value. In particular, @code{ess-eval-buffer} is now largely
1864 One final command is provided for spot-evaluations of @Sl{} code:
1867 @kbd{C-c C-t} (@code{ess-execute-in-tb}) @*
1868 @pindex ess-execute-in-tb
1869 Prompt for an @Sl{} expression and evaluate it. Displays result in a
1874 This is useful for quick calculations, etc.
1876 All the above commands are useful for evaluating small amounts of code
1877 and observing the results in the process buffer. A useful way to work
1878 is to divide the frame into two windows; one containing the source code
1879 and the other containing the process buffer. If you wish to make the
1880 process buffer scroll automatically when the output reaches the bottom
1881 of the window, you will need to set the variable
1882 @code{comint-scroll-to-bottom-on-output} to @code{'others} or @code{t}.
1885 @comment node-name, next, previous, up
1886 @node Indenting, Other edit buffer commands, Evaluating code, Editing
1887 @section Indenting and formatting S code
1889 ESS now provides a sophisticated mechanism for indenting @Sl{} source
1890 code (thanks to Ken'ichi Shibayama). Compound statements (delimited by
1891 @samp{@{} and @samp{@}}) are indented relative to their enclosing block.
1892 In addition, the braces have been electrified to automatically indent to
1893 the correct position when inserted, and optionally insert a newline at
1894 the appropriate place as well. Lines which continue an incomplete
1895 expression are indented relative to the first line of the expression.
1896 Function definitions, @code{if} statements, calls to @code{expression()}
1897 and loop constructs are all recognized and indented appropriately. User
1898 variables are provided to control the amount if indentation in each
1899 case, and there are also a number of predefined indentation styles to
1902 @cindex comments in S
1903 Comments are also handled specially by ESS, using an idea borrowed from
1904 the Emacs-Lisp indentation style. By default,
1905 comments beginning with @samp{###}
1906 are aligned to the beginning of the line. Comments beginning with
1907 @samp{##} are aligned to the current level of indentation for the block
1908 containing the comment. Finally, comments beginning with @samp{#} are
1909 aligned to a column on the right (the 40th column by default, but this
1910 value is controlled by the variable @code{comment-column},)
1911 @vindex comment-column
1912 or just after the expression on the line containing the comment if it
1913 extends beyond the indentation column. You turn off the default
1914 behavior by adding the line
1915 @code{(setq ess-fancy-comments nil)} to your @file{.emacs} file.
1916 @vindex ess-fancy-comments
1918 The indentation commands provided by ESS are:
1920 @cindex formatting source code
1924 @kbd{TAB} (@code{ess-indent-command}) @*
1925 Indents the current line as @Sl{} code. If a prefix argument is given,
1926 all following lines which are part of the same (compound) expression are
1927 indented by the same amount (but relative indents are preserved).
1930 @kbd{RET} (@code{newline-and-indent}) @*
1931 @kbd{LFD} (@emph{newline-and-indent}) @*
1932 Insert a newline, and indent the next line. (Note that most keyboards
1933 nowadays do not have a @key{LINEFEED} key, but @kbd{C-j} is equivalent.)
1936 @kbd{ESC C-q} aka @kbd{M-C-q} aka @kbd{C-M-q} (@code{ess-indent-exp}) @*
1937 Indents each line in the @Sl{} (compound) expression which follows point.
1938 Very useful for beautifying your @Sl{} code.
1941 @kbd{@{} and @kbd{@}} (@code{ess-electric-brace}) @*
1942 The braces automatically indent to the correct position when typed.
1945 @kbd{M-;} (@code{indent-for-comment}) @*
1946 Indents an existing comment line appropriately, or inserts an
1947 appropriate comment marker.
1950 @kbd{M-x ess-set-style} @*
1951 Set the formatting style in this buffer to be one of the predefined
1952 styles: @code{GNU}, @code{BSD}, @code{K&R}, @code{CLB}, and @code{C++}.
1953 The @code{DEFAULT} style uses the default values for the indenting
1954 variables (unless they have been modified in your @file{.emacs} file.)
1955 @cindex @file{.emacs} file
1956 This command causes all of the formatting variables to be buffer-local.
1959 @comment node-name, next, previous, up
1960 @node Other edit buffer commands, Source Files, Indenting, Editing
1961 @section Commands for motion, completion and more
1963 A number of commands are provided to move across function definitions
1967 @kbd{ESC C-a} aka @kbd{C-M-a} (@code{ess-beginning-of-function}) @*
1968 @pindex ess-beginning-of-function
1969 Moves point to the beginning of the function containing point.
1972 @kbd{ESC C-e} aka @kbd{C-M-e} (@code{ess-end-of-function}) @*
1973 @pindex ess-end-of-function
1974 Moves point to the end of the function containing point.
1977 @kbd{ESC C-h} aka @kbd{C-M-h} (@code{ess-mark-function}) @*
1978 Places point at the beginning of the @Sl{} function containing point, and
1982 Don't forget the usual Emacs commands for moving over balanced
1983 expressions and parentheses: @xref{Lists, Lists and Sexps, Lists and
1984 Sexps, Emacs, The GNU Emacs Reference Manual}.
1986 @cindex completion in edit buffer
1987 Completion is provided in the edit buffer in a similar fashion to the
1988 process buffer: @kbd{M-TAB} completes file names and @kbd{M-?} lists
1989 file completions. Since @key{TAB} is used for indentation in the edit
1990 buffer, object completion is now performed with @kbd{C-c TAB}. Note
1991 however that completion is only provided over globally known S objects
1992 (such as system functions) --- it will @emph{not} work for arguments to
1993 functions or other variables local to the function you are editing.
1995 Finally, two commands are provided for returning to the ESS process buffer:
1999 @kbd{C-c C-z} (@code{ess-switch-to-end-of-ESS}) @*
2000 @pindex ess-switch-to-end-of-ESS
2001 Returns you to the ESS process buffer, placing point at the end of the
2005 @kbd{C-c C-y} (@code{ess-switch-to-ESS}) @*
2006 @pindex ess-switch-to-ESS
2007 Also returns to to the ESS process buffer, but leaves point where it was.
2010 In addition some commands available in the process buffer are also
2011 available in the edit buffer. You can still read help files with
2012 @kbd{C-c C-v}, edit another function with @kbd{C-c C-d} and of course
2013 @kbd{C-c C-l} can be used to load a source file into S. @xref{Other},
2014 for more details on these commands.
2016 @comment node-name, next, previous, up
2017 @node Source Files, Source Directories, Other edit buffer commands, Editing
2018 @section Maintaining S source files
2020 Every edit buffer in ESS is associated with a @dfn{dump file} on disk.
2021 Dump files are created whenever you type @kbd{C-c C-d}
2022 (@code{ess-dump-object-into-edit-buffer}), and may either be deleted
2023 after use, or kept as a backup file or as a means of keeping several
2024 versions of an @Sl{} function.
2027 @defvr {User Option} ess-delete-dump-files
2028 If non-@code{nil}, dump files created with C-c C-d are deleted
2029 immediately after they are created by the ess-process.
2032 Since immediately after @Sl{} dumps an object's definition to a disk
2033 file the source code on disk corresponds exactly to S's idea of the
2034 object's definition, the disk file isn't needed; deleting it now has the
2035 advantage that if you @emph{don't} modify the file (say, because you
2036 just wanted to look at the definition of one of the standard S
2037 functions) the source dump file won't be left around when you kill the
2038 buffer. Note that this variable only applies to files generated with
2039 S's @code{dump} function; it doesn't apply to source files which already
2040 exist. The default value is @code{t}.
2042 @defvr {User Option} ess-keep-dump-files
2043 Option controlling what to do with the dump file after an object has
2044 been successfully loaded into S. Valid values are @code{nil} (always
2045 delete), @code{ask} (always ask whether to delete), @code{check} (delete
2046 files generated with @kbd{C-c C-d} in this Emacs session, otherwise ask
2047 --- this is the default) and @code{t} (never delete). This variable is
2051 After an object has been successfully (i.e. without error) loaded
2052 back into @Sl{} with @kbd{C-c C-l}, the disk file again corresponds
2053 exactly (well, almost --- see below) to S's record of the object's
2054 definition, and so some people prefer to delete the disk file rather
2055 than unnecessarily use up space. This option allows you to do just
2059 @cindex project work in S
2060 @cindex historic backups
2061 If the value of @code{ess-keep-dump-files} is @code{t}, dump files are
2062 never deleted after they are loaded. Thus you can maintain a complete
2063 text record of the functions you have edited within ESS. Backup files
2064 are kept as usual, and so by using the Emacs numbered backup facility ---
2065 @pxref{Backup Names, Single or Numbered Backups, Single or Numbered
2066 Backups, emacs, The Gnu Emacs Reference Manual}, you can keep a historic
2067 record of function definitions. Another possibility is to maintain the
2068 files with a version-control system such as RCS @xref{Version Control,
2069 Version Control, Version Control, emacs, The Gnu Emacs Reference
2070 Manual}. As long as a dump file exists in the appropriate place for a
2071 particular object, editing that object with @kbd{C-c C-d} finds that
2072 file for editing (unless a prefix argument is given) --- the ESS
2073 process is not consulted. Thus you can keep comments @emph{outside} the
2074 function definition as a means of documentation that does not clutter
2075 the @Sl{} object itself. Another useful feature is that you may format
2076 the code in any fashion you please without @Sl{} re-indenting the code
2077 every time you edit it. These features are particularly useful for
2080 If the value of @code{ess-keep-dump-files} is nil, the dump file is always
2081 silently deleted after a successful load with @kbd{C-c C-l}. While this
2082 is useful for files that were created with @kbd{C-c C-d} it also applies
2083 to any other file you load (say, a source file of function
2084 definitions), and so can be dangerous to use unless you are careful.
2085 Note that since @code{ess-keep-dump-files} is buffer-local, you can make
2086 sure particular files are not deleted by setting it to @code{t} in the
2087 Local Variables section of the file @xref{File Variables, Local
2088 Variables in Files, Local Variables in Files, emacs, The Gnu Emacs
2091 A safer option is to set @code{ess-keep-dump-files} to @code{ask}; this
2092 means that ESS will always ask for confirmation before deleting the
2093 file. Since this can get annoying if you always want to delete dump
2094 files created with @code{C-c C-d}, but not any other files, setting
2095 @code{ess-keep-dump-files} to @code{check} (the default value) will
2096 silently delete dump files created with @kbd{C-c C-d} in the current
2097 Emacs session, but query for any other file. Note that in any case you
2098 will only be asked for confirmation once per file, and your answer is
2099 remembered for the rest of the Emacs session.
2101 Note that in all cases, if an error (such as a syntax error) is detected
2102 while loading the file with @kbd{C-c C-l}, the dump file is @emph{never}
2103 deleted. This is so that you can edit the file in a new Emacs session
2104 if you happen to quit Emacs before correcting the error.
2107 Dump buffers are always autosaved, regardless of the value of
2108 @code{ess-keep-dump-files}.
2110 @comment node-name, next, previous, up
2111 @node Source Directories, , Source Files, Editing
2112 @section Names and locations of dump files
2114 @cindex dump file names
2115 Every dump file should be given a unique file name, usually the dumped
2116 object name with some additions.
2118 @defvr {User Option} ess-dump-filename-template
2119 Template for filenames of dumped objects. @code{%s} is replaced by the
2124 By default, dump file names are the user name, followed by @samp{.} and
2125 the object and ending with @samp{.S}. Thus if user @code{joe} dumps the
2126 object @code{myfun} the dump file will have name @file{joe.myfun.S}.
2127 The username part is included to avoid clashes when dumping into a
2128 publicly-writable directory, such as @file{/tmp}; you may wish to remove
2129 this part if you are dumping into a directory owned by you.
2131 @cindex dump file directories
2132 You may also specify the directory in which dump files are written:
2134 @defvr {User Option} ess-source-directory
2135 Directory name (ending in a slash) where @Sl{} dump files are to be written.
2138 By default, dump files are always written to @file{/tmp}, which is fine
2139 when @code{ess-keep-dump-files} is @code{nil}. If you are keeping dump
2140 files, then you will probably want to keep them somewhere in your home
2141 directory, say @file{~/S-source}. This could be achieved by including
2142 the following line in your @file{.emacs} file:
2143 @cindex @file{.emacs} file
2145 (setq ess-source-directory (expand-file-name "~/S-source/"))
2148 If you would prefer to keep your dump files in separate directories
2149 depending on the value of some variable, ESS provides a facility for
2150 this also. By setting @code{ess-source-directory} to a lambda
2151 expression which evaluates to a directory name, you have a great deal of
2152 flexibility in selecting the directory for a particular source file to
2153 appear in. The lambda expression is evaluated with the process buffer
2154 as the current buffer and so you can use the variables local to that
2155 buffer to make your choice. For example, the following expression
2156 causes source files to be saved in the subdirectory @file{Src} of the
2157 directory the ESS process was run in.
2160 (setq ess-source-directory
2162 (concat ess-directory "Src/")))
2166 @vindex ess-directory
2167 (@code{ess-directory} is a buffer-local variable in process buffers
2168 which records the directory the ESS process was run from.) This is
2169 useful if you keep your dump files and you often edit objects with the
2170 same name in different ESS processes. Alternatively, if you often
2171 change your @Sl{} working directory during an @Sl{} session, you may
2172 like to keep dump files in some subdirectory of the directory pointed to
2173 by the first element of the current search list. This way you can edit
2174 objects of the same name in different directories during the one S
2177 @cindex working directory
2179 (setq ess-source-directory
2181 (file-name-as-directory
2182 (expand-file-name (concat
2183 (car ess-search-list)
2186 @vindex ess-search-list
2188 If the directory generated by the lambda function does not exist but can
2189 be created, you will be asked whether you wish to create the directory.
2190 If you choose not to, or the directory cannot be created, you will not
2191 be able to edit functions.
2193 @node Editing R documentation files, Help, Editing, Top
2194 @chapter Editing R documentation files
2196 ESS also provides support for editing @dfn{R documentation} (``Rd'')
2197 files. @R{} objects are documented in files written in Rd format, a
2198 simple markup language closely resembling (La)@TeX{}, which can be
2199 processed into a variety of formats, including La@TeX{}, @acronym{HTML},
2200 and plain text. Rd format is described in section ``Rd format'' of the
2201 ``Writing R Extensions'' manual in the R distribution.
2203 Visiting an Rd file as characterized by its extension @file{Rd} will
2204 activate Rd Mode, which provides several facilities for making editing R
2205 documentation files more convenient, by helping with indentation,
2206 insertions, even doing some of the typing for you (with Abbrev Mode),
2207 and by showing Rd keywords, strings, etc.@: in different faces (with
2210 Note that R also accepts Rd files with extension @file{rd}; to activate
2211 @ESS{[Rd]} support for this extension, you may need to add
2214 (add-to-list 'auto-mode-alist '("\\.rd\\'" . Rd-mode))
2218 to one of your Emacs startup files.
2220 In Rd mode, the following special Emacs commands can be used in addition
2221 to the standard Emacs commands.
2225 Describe the features of Rd mode.
2229 Reindent the current line, insert a newline and indent the new line
2230 (@code{reindent-then-newline-and-indent}). An abbrev before point is
2231 expanded if @code{abbrev-mode} is non-@code{nil}.
2234 Indent current line based on its contents and on previous lines
2235 (@code{indent-according-to-mode}).
2238 Insert a ``skeleton'' with Rd markup for at least all mandatory entries
2239 in Rd files (@code{Rd-mode-insert-skeleton}). Note that many users
2240 might prefer to use the R function @code{prompt} on an existing R object
2241 to generate a non-empty Rd ``shell'' documenting the object (which
2242 already has all information filled in which can be obtained from the
2246 Insert ``font'' specifiers for some of the Rd markup commands markup
2247 available for emphasizing or quoting text, including markup for URLs and
2248 email addresses (@code{Rd-font}). @kbd{C-c C-f} is only a prefix; see
2249 e.g.@: @kbd{C-c C-f TAB} for the available bindings. Note that
2250 currently, not all of the Rd text markup as described in section
2251 ``Marking text'' of ``Writing R Extensions'' can be accessed via
2255 Insert a suitably indented @samp{\item@{} on the next line
2256 (@code{Rd-mode-insert-item}).
2259 Preview a plain text version (``help file'', @pxref{Help}) generated
2260 from the Rd file (@code{Rd-preview-help}).
2263 In addition, when editing Rd files one can interact with a running R
2264 process in a similar way as when editing R language files. E.g.,
2265 @kbd{C-c C-v} provides access to on-line help, and @kbd{C-c C-n} sends
2266 the current line to the R process for evaluation. This interaction is
2267 particularly useful when editing the examples in the Rd file. See
2268 @kbd{C-h m} for all available commands.
2270 Rd mode also provides access to abbreviations for most of the Rd markup
2271 commands. Type @kbd{M-x list-abbrevs} with Abbrev mode turned on to
2272 list all available abbrevs. Note that all Rd abbrevs start with a grave
2275 Rd mode can be customized via the following variables.
2279 Hook to be run when Rd mode is entered.
2280 @item Rd-indent-level
2281 The indentation of Rd code with respect to containing blocks. Default
2283 @item Rd-to-help-command
2284 The shell command used for converting Rd source to help text. Default
2285 is @samp{R CMD Rd2txt}.
2288 To automatically turn on the abbrev and font-lock features of Rd mode,
2289 add the following lines to one of your Emacs startup files:
2292 (add-hook 'Rd-mode-hook
2295 (font-lock-mode 1)))
2299 @comment node-name, next, previous, up
2300 @node Help, ESS for SAS, Editing R documentation files, Top
2301 @chapter Reading help files
2304 ESS provides an easy-to-use facility for reading @Sl{} help files from
2305 within Emacs. From within the ESS process buffer or any ESS edit
2306 buffer, typing @kbd{C-c C-v} (@code{ess-display-help-on-object})
2307 @pindex ess-display-help-on-object
2308 will prompt you for the name of an object for which you would like
2309 documentation. Completion is provided over all objects which have help
2312 If the requested object has documentation, you will be popped into a
2313 buffer (named @code{*help(@var{obj-name})*}) containing the help file.
2314 This buffer is placed in a special `S Help' mode which disables the
2315 usual editing commands but which provides a number of keys for paging
2316 through the help file:
2322 @kbd{?} (@code{ess-describe-help-mode}) @*
2323 @pindex ess-describe-help-mode
2324 Pops up a help buffer with a list of the commands available in @Sl{} help
2328 @kbd{h} (@code{ess-display-help-on-object}) @*
2329 @pindex ess-display-help-on-object
2330 Pop up a help buffer for a different object
2334 @cindex paging commands in help buffers
2336 @kbd{b} or @kbd{DEL} (@code{scroll-down}) @*
2337 Move one page backwards through the help file.
2340 @kbd{SPC} (@code{scroll-up}) @*
2341 Move one page forwards through the help file.
2344 @kbd{>} (@code{beginning-of-buffer}) and @kbd{<} (@code{end-of-buffer})
2346 Move to the beginning and end of the help file, respectively.
2348 Section-based motion commands:
2351 @kbd{n} (@code{ess-skip-to-next-section}) and @kbd{p}
2352 (@code{ess-skip-to-previous-section}) @* Move to the next and previous
2353 @pindex ess-skip-to-next-section
2354 @pindex ess-skip-to-previous-section
2355 section header in the help file, respectively. A section header
2356 consists of a number of capitalized words, followed by a colon.
2358 In addition, the @kbd{s} key followed by one of the following letters
2359 will jump to a particular section in the help file:
2360 @pindex ess-skip-to-help-section
2405 Jumps to beginning of file
2408 Jumps to end of file
2411 Pops up a help buffer with a list of the defined section motion keys.
2417 @kbd{l} (@code{ess-eval-line-and-step}) @*
2418 @pindex ess-eval-line-and-step
2419 Evaluates the current line in the ESS process, and moves to the next
2420 line. Useful for running examples in help files.
2423 @kbd{r} (@code{ess-eval-region}) @*
2424 @pindex ess-eval-region
2425 Send the contents of the current region to the ESS process. Useful
2426 for running examples in help files.
2429 @kbd{/} (@code{isearch-forward}) @*
2435 @kbd{q} (@code{ess-switch-to-end-of-ESS}) @*
2436 @pindex ess-switch-to-end-of-ESS
2437 Returns to the ESS process buffer in another window, leaving the
2438 help window visible.
2441 @kbd{k} (@code{kill-buffer}) @*
2442 Kills the help buffer.
2445 @kbd{x} (@code{ess-kill-buffer-and-go}) @*
2446 Return to the ESS process, killing this help buffer.
2449 In addition, all of the ESS commands available in the edit buffers are
2450 also available in @Sl{} help mode (@pxref{Edit buffer}). Of course, the
2451 usual (non-editing) Emacs commands are available, and for convenience
2452 the digits and @key{-} act as prefix arguments.
2454 If a help buffer already exists for an object for which help is
2455 requested, that buffer is popped to immediately; the ESS process is
2456 not consulted at all. If the contents of the help file have changed,
2457 you either need to kill the help buffer first, or pass a prefix argument
2458 (with @kbd{C-u}) to @code{ess-display-help-on-object}.
2460 Help buffers are marked as temporary buffers in ESS, and are deleted
2461 when @code{ess-quit} or @code{ess-cleanup} are called.
2463 Help buffers normally appear in another window within the current
2464 frame. If you wish help buffers to appear in their own frame (either
2465 one per help buffer, or one for all help buffers), you can customize the
2466 variable @code{ess-help-own-frame}.
2470 @cindex temporary buffers
2472 @comment node-name, next, previous, up
2473 @node ESS for SAS, ESS for BUGS, Help, Top
2474 @chapter ESS for SAS
2477 * ESS(SAS)--Design philosophy::
2478 * ESS(SAS)--Editing files::
2479 * ESS(SAS)--TAB key::
2480 * ESS(SAS)--Batch SAS processes::
2481 * ESS(SAS)--Function keys for batch processing::
2482 * iESS(SAS)--Interactive SAS processes::
2483 * iESS(SAS)--Common problems::
2484 * ESS(SAS)--Graphics::
2485 * ESS(SAS)--Windows::
2487 @include help-sas.texi
2489 @comment node-name, next, previous, up
2490 @node ESS for BUGS, Miscellaneous, ESS for SAS, Top
2491 @chapter ESS for BUGS
2494 * ESS(BUGS)--Model files::
2495 * ESS(BUGS)--Command files::
2496 * ESS(BUGS)--Log files::
2498 @include help-bugs.texi
2500 @comment node-name, next, previous, up
2501 @node Miscellaneous, Mailing lists/bug reports, ESS for BUGS, Top
2502 @chapter Other features of ESS
2504 ESS has a few miscellaneous features, which didn't fit anywhere else.
2507 * Highlighting:: Syntactic highlighting of buffers
2508 * Parens:: Parenthesis matching
2509 * Graphics:: Using graphics with ESS
2510 * Imenu:: Support for Imenu in ESS
2511 * Toolbar:: Support for toolbar in ESS
2512 * TAGS:: Using TAGS for S files
2513 * Rdired:: Directory editor for R objects
2516 @comment node-name, next, previous, up
2517 @node Highlighting, Parens, Miscellaneous, Miscellaneous
2518 @section Syntactic highlighting of buffers
2520 ESS provides Font-Lock (@pxref{Faces,,Using Multiple Typefaces,
2521 emacs, The Gnu Emacs Reference Manual}) patterns for Inferior @Sl{} Mode, S
2522 Mode, and @Sl{} Transcript Mode buffers.
2523 @cindex Font-lock mode
2524 @cindex highlighting
2526 To activate highlighting, you need to turn on Font Lock mode in the
2527 appropriate buffers. This can be done on a per-buffer basis with
2528 @kbd{M-x font-lock-mode}, or may be done by adding
2529 @code{turn-on-font-lock} to @code{inferior-ess-mode-hook},
2530 @code{ess-mode-hook} and @code{ess-transcript-mode-hook}. Your systems
2531 administrator may have done this for you in @file{ess-site.el}
2532 (@pxref{Customization}).
2534 The font-lock patterns are defined in three variables, which you may
2537 @defvar inferior-ess-font-lock-keywords
2538 Font-lock patterns for Inferior ESS Mode. The default value
2539 highlights prompts, inputs, assignments, output messages, vector and
2540 matrix labels, and literals such as @samp{NA} and @code{TRUE}.
2543 @defvar ess-mode-font-lock-keywords
2544 Font-lock patterns for ESS programming mode. The default value
2545 highlights function names, literals, assignments, source functions and
2549 @defvar ess-trans-font-lock-keywords
2550 Font-lock patterns for ESS Transcript Mode. The default value
2551 highlights the same patterns as in Inferior ESS Mode.
2554 @comment node-name, next, previous, up
2555 @node Parens, Graphics, Highlighting, Miscellaneous
2556 @section Parenthesis matching
2558 Emacs and XEmacs have facilities for highlighting the parenthesis
2559 matching the parenthesis at point. This feature is very useful when
2560 trying to examine which parentheses match each other. This highlighting
2561 also indicates when parentheses are not matching. Depending on what
2562 version of emacs you use, one of the following should work in your
2563 initialisation file:
2566 (paren-set-mode 'paren) ;for XEmacs
2567 (show-paren-mode t) ;for Emacs
2574 @comment node-name, next, previous, up
2575 @node Graphics, Imenu, Parens, Miscellaneous
2576 @section Using graphics with ESS
2579 One of the main features of the @code{S} package is its ability to
2580 generate high-resolution graphics plots, and ESS provides a number of
2581 features for dealing with such plots.
2584 * printer:: The printer() graphics driver
2585 * X11:: The X11() (and other X-windows based) driver
2586 * winjava:: Java Graphics Device
2589 @comment node-name, next, previous, up
2590 @node printer, X11, Graphics, Graphics
2591 @subsection Using ESS with the @code{printer()} driver
2593 This is the simplest (and least desirable) method of using graphics
2594 within ESS. S's @code{printer()} device driver produces crude character
2595 based plots which can be contained within the ESS process buffer
2596 itself. To start using character graphics, issue the @Sl{} command
2601 (the @code{width=79} argument prevents Emacs line-wrapping at column
2602 80 on an 80-column terminal. Use a different value for a terminal with
2603 a different number of columns.) Plotting commands do not generate
2604 graphics immediately, but are stored until the @code{show()} command
2605 is issued, which displays the current figure.
2607 @comment node-name, next, previous, up
2608 @node X11, winjava, printer, Graphics
2609 @subsection Using ESS with windowing devices
2612 Of course, the ideal way to use graphics with ESS is to use a windowing
2613 system. Under X11, this requires that the DISPLAY environment
2614 variable be appropriately set, which may not always be the case within
2615 your Emacs process. ESS provides a facility for setting the value of
2616 DISPLAY before the ESS process is started if the variable
2617 @code{ess-ask-about-display}
2618 @pindex ess-ask-about-display
2621 @comment node-name, next, previous, up
2622 @node winjava, , X11, Graphics
2623 @subsection Java Graphics Device
2627 S+6.1 and newer on Windows contains a java library that supports graphics. Send
2635 @noindent to start the graphics driver. This allows you to use ESS for both
2636 interaction and graphics within S-PLUS. (Thanks to Tim Hesterberg for
2639 @comment node-name, next, previous, up
2640 @node Imenu, Toolbar, Graphics, Miscellaneous
2643 Imenu is an Emacs tool for providing mode-specific buffer indexes. In
2644 some of the ESS editing modes (currently SAS and S), support for Imenu
2645 is provided. For example, in S mode buffers, the menubar should display
2646 an item called "Imenu-S". Within this menubar you will then be offered
2647 bookmarks to particular parts of your source file (such as the starting
2648 point of each function definition).
2650 Imenu works by searching your buffer for lines that match what ESS
2651 thinks is the beginning of a suitable entry, e.g. the beginning of a
2652 function definition. To examine the regular expression that ESS uses,
2653 check the value of @code{imenu-generic-expression}. This value is set
2654 by various ESS variables such as @code{ess-imenu-S-generic-expression}.
2656 @comment node-name, next, previous, up
2657 @node Toolbar, TAGS, Imenu, Miscellaneous
2660 The R and S editing modes have support for a toolbar. This toolbar
2661 provides icons to act as shortcuts for starting new S/R processes, or
2662 for evaluating regions of your source buffers. The toolbar should be
2663 present if your emacs can display images. @xref{Customization}, for ways
2664 to change the toolbar.
2666 @comment node-name, next, previous, up
2667 @node TAGS, Rdired, Toolbar, Miscellaneous
2670 The Emacs tags facility can be used to navigate around your files
2671 containing definitions of S functions. This facility is independent of
2672 ESS usage, but is written here since ESS users may wish to take
2673 advantage of TAGS facility. Read more about emacs tags in an emacs
2676 Etags, the program that generates the TAGS file, does not yet know the
2677 syntax to recognise function definitions in S files. Hence, you will
2678 need to provide a regexp that matches your function definitions. Here
2679 is an example call (broken over two lines; type as one line) that should
2683 etags --language=none
2684 --regex='/\([^ \t]+\)[ \t]*<-[ \t]*function/\1/' *.R
2687 This will find entries in your source file of the form:
2690 some.name <- function
2693 with the function name starting in column 0. Windows users may need to
2694 change the single quotes to double quotes.
2696 @comment node-name, next, previous, up
2697 @node Rdired, , TAGS, Miscellaneous
2700 Ess-rdired provides a dired-like buffer for viewing, editing and
2701 plotting objects in your current R session. If you are used to using
2702 the dired (directory editor) facility in Emacs, this mode gives you
2703 similar functionality for R objects.
2705 To get started, first make sure you can load ess-rdired. Add the
2706 following to your .emacs and then restart emacs.
2708 (autoload 'ess-rdired "ess-rdired"
2709 "View *R* objects in a dired-like buffer." t)
2712 Start an R session with @kbd{M-x R} and then store a few
2716 s <- sin(seq(from=0, to=8*pi, length=100))
2722 Then use @kbd{M-x ess-rdired} to create a buffer listing the
2723 objects in your current environment and display it in a new window:
2732 Type @kbd{C-h m} or @kbd{?} to get a list of the keybindings for this
2733 mode. For example, with your point on the line of a variable, `p' will
2734 plot the object, `v' will view it, and `d' will mark the object for
2735 deletion (`x' will actually perform the deletion).
2737 @comment node-name, next, previous, up@chapter Using S4
2738 @node Mailing lists/bug reports, Customization, Miscellaneous, Top
2739 @chapter Bugs and Bug Reporting, Mailing Lists
2748 @node Bugs, Reporting Bugs, Mailing lists/bug reports, Mailing lists/bug reports
2753 @comment node-name, next, previous, up
2754 @node Reporting Bugs, Mailing Lists, Bugs, Mailing lists/bug reports
2755 @section Reporting Bugs
2757 @pindex ess-submit-bug-report
2758 @include bugrept.texi
2760 @comment node-name, next, previous, up
2761 @node Mailing Lists, Help with emacs, Reporting Bugs, Mailing lists/bug reports
2762 @section Mailing Lists
2764 @include mailing.texi
2766 @comment node-name, next, previous, up
2767 @node Help with emacs, , Mailing Lists, Mailing lists/bug reports
2768 @section Help with emacs
2770 Emacs is a complex editor with many abilities that we do not have space
2771 to describe here. If you have problems with other features of emacs
2772 (e.g. printing), there are several sources to consult, including the
2773 emacs FAQs (try @kbd{M-x xemacs-www-faq} or @kbd{M-x view-emacs-FAQ})
2774 and EmacsWiki (@uref{http://www.emacswiki.org}). Please consult them
2775 before asking on the mailing list about issues that are not specific to
2779 @c _not_yet_ @node Help OS, Installation, Help for Statistical Packages, Top
2780 @c _not_yet_ @comment node-name, next, previous, up
2781 @c _not_yet_ @chapter Help, arranged by Operating System
2784 @c _not_yet_ * Unix installation::
2785 @c _not_yet_ * Microsoft Windows installation::
2786 @c _not_yet_ * System dependent:: Other variables you may need to change
2787 @c _not_yet_ @end menu
2791 @comment node-name, next, previous, up
2792 @node Customization, Key Index, Mailing lists/bug reports, Top
2793 @appendix Customizing ESS
2794 @cindex customization
2796 ESS can be easily customized to your taste simply by including the
2797 appropriate lines in your @file{.emacs} file. There are numerous
2798 variables which affect the behavior of ESS in certain situations which
2799 can be modified to your liking. Keybindings may be set or changed to
2800 your preferences, and for per-buffer customizations hooks are also
2803 Most of these variables can be viewed and set using the Custom facility
2804 within Emacs. Type @kbd{M-x customize-group RET ess RET} to see all the
2805 ESS variables that can be customized. Variables are grouped by subject
2806 to make it easy to find related variables.
2808 @c Stephen deleted incomplete variable list Wed 25 Aug 2004.
2810 @node Key Index, Concept Index, Customization, Top
2811 @unnumbered Key (Character) Index
2815 @c @node Command Index, Concept Index, Key Index, Top
2816 @c @unnumbered Command and Function Index
2820 @comment node-name, next, previous, up
2821 @node Concept Index, Variable and command index, Key Index, Top
2822 @unnumbered Concept Index
2825 @node Variable and command index, , Concept Index, Top
2826 @unnumbered Variable and command index
2832 @c Remember to delete these lines before creating the info file.
2833 @c Why? I makeinfo all of the time without following this advice.
2836 @bindingoffset = 0.5in
2840 @comment Local Variables:
2841 @comment TeX-master: "ess.texi"