| blob | 4650988df34bc5f5ea1b19ba7779a8db9c34e83a |
2 <head>
21 </head>
22 <body>
26 <!-- node-name, next, previous, up -->
28 <p><hr>
34 </div>
38 <p>ESS version
39 5.3.7
42 R.M. Heiberger,
43 K. Hornik,
44 M. Maechler,
45 R.A. Sparapani
46 and S.J. Eglen.
47 </pre>
48 <!-- (Formerly: Doug -->
49 <!-- Bates, Ed Kademan, Frank Ritter and David Smith). -->
50 <blockquote>
51 Emacs Speaks Statistics (ESS) provides an intelligent, consistent
52 interface between the user and the software. ESS interfaces with
53 SAS, S-PLUS, R, BUGS and other statistical analysis packages under
54 the Unix, Microsoft Windows, and Apple Mac operating systems. ESS
55 is itself a package within the emacs text editor and uses emacs
56 features to streamline the creation and use of statistical software.
57 ESS knows the syntax and grammar of statistical analysis packages
58 and provides consistent display and editing features based on that
59 knowledge. ESS assists in interactive and batch execution of
60 statements written in these statistical analysis languages.
61 </blockquote>
64 <li><a accesskey="1" href="#Introduction">Introduction</a>: Overview of features provided by this package
67 <li><a accesskey="3" href="#Interactive-ESS">Interactive ESS</a>: Interacting with statistical programs
68 <li><a accesskey="4" href="#Entering-commands">Entering commands</a>: Interacting with the ESS process
69 <li><a accesskey="5" href="#Transcript-Mode">Transcript Mode</a>: Manipulating saved transcript files
80 <li><a href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>: How to get assistance with ESS
86 <!-- @detailmenu -->
87 <!-- The Detailed Node Listing - -->
88 <!-- Introduction to ESS -->
89 <!-- * Features:: Why should I use ESS? -->
90 <!-- * New features:: -->
91 <!-- * Credits:: Authors of and contributors to ESS -->
92 <!-- * Latest version:: Getting the latest version of ESS -->
93 <!-- * Manual:: How to read this manual -->
94 <!-- Installing ESS on your system -->
95 <!-- * Unix installation:: Installing ESS on your Unix system -->
96 <!-- * Microsoft Windows installation:: Installing ESS on your MS Windows system -->
97 <!-- * Requirements:: emacs, Operating Systems and Statistical Packages -->
98 <!-- * System dependent:: Other variables you may need to change -->
99 <!-- Starting the ESS process -->
100 <!-- * Multiple ESS processes:: -->
101 <!-- * ESS processes on Remote Computers:: -->
102 <!-- * Customizing startup:: Changing the startup actions -->
103 <!-- Help for the S family -->
104 <!-- * ESS(S)-Editing files:: -->
105 <!-- * iESS(S)-Inferior ESS processes:: -->
106 <!-- * Handling and Reusing Transcripts:: -->
107 <!-- * ESS-help-assistance with viewing help:: -->
108 <!-- * Philosophies for using ESS(S):: -->
109 <!-- * Scenarios for use (possibilities-based on actual usage):: -->
110 <!-- * Customization Examples and Solutions to Problems:: -->
111 <!-- Help for SAS -->
112 <!-- * ESS(SAS)-Design philosophy:: -->
113 <!-- * ESS(SAS)-Editing files:: -->
114 <!-- * iESS(SAS)-Interactive SAS processes:: -->
115 <!-- * ESS(SAS)-Batch SAS processes:: -->
116 <!-- * ESS(SAS)-Function keys for batch processing:: -->
117 <!-- * ESS(SAS)-TAB key:: -->
118 <!-- * ESS(SAS)-Usage scenarios:: -->
119 <!-- * iESS(SAS)-Common problems:: -->
120 <!-- * ESS(SAS)-MS Windows:: -->
121 <!-- Interacting with the ESS process -->
122 <!-- * Command-line editing:: Entering commands and fixing mistakes -->
123 <!-- * Completion:: Completion of object names -->
124 <!-- * Completion details:: Advanced completion concepts -->
125 <!-- * Transcript:: Manipulating the transcript -->
126 <!-- * Command History:: Command History -->
127 <!-- * History expansion:: References to historical commands -->
128 <!-- * Hot keys:: Hot keys for common commands -->
129 <!-- * Statistical Process running in ESS?:: -->
130 <!-- * Other:: Other commands provided by inferior-ESS -->
131 <!-- Manipulating the transcript -->
132 <!-- * Last command:: Manipulating the output from the last command -->
133 <!-- * Process buffer motion:: Viewing older commands -->
134 <!-- * Transcript resubmit:: Re-submitting commands from the transcript -->
135 <!-- * Saving transcripts:: Keeping a record of your S session -->
136 <!-- Editing S functions -->
137 <!-- * Edit buffer:: Edit objects in a specialized buffer -->
138 <!-- * Loading:: Loading source files into the ESS process -->
139 <!-- * Error Checking:: Detecting errors in source files -->
140 <!-- * Evaluating code:: Sending code to the ESS process -->
141 <!-- * Indenting:: Indenting and formatting @Sl{} code -->
142 <!-- * Other edit buffer commands:: Commands for motion, completion and more -->
143 <!-- * Source Files:: Maintaining @Sl{} source files -->
144 <!-- * Source Directories:: Names and locations of dump files -->
145 <!-- Manipulating saved transcript files -->
146 <!-- * Resubmit:: Resubmitting commands from the transcript file -->
147 <!-- * Clean:: Cleaning transcript files -->
148 <!-- Other features of ESS -->
149 <!-- * Highlighting:: Syntactic highlighting of buffers -->
150 <!-- * Graphics:: Using graphics with ESS -->
151 <!-- * Object Completion:: -->
152 <!-- Using graphics with ESS -->
153 <!-- * printer:: The printer() graphics driver -->
154 <!-- * X11:: The X11() (and other X-windows based) driver -->
155 <!-- Bugs and Bug Reporting, Mailing Lists -->
156 <!-- * Bugs:: -->
157 <!-- * Reporting Bugs:: -->
158 <!-- * Mailing Lists:: -->
159 <!-- Customizing ESS -->
160 <!-- * Variables:: Variables for customization -->
161 <!-- * Hooks:: Customizing ESS with hooks -->
162 <!-- * Keybindings:: Changing the default ESS keybindings -->
163 <!-- Variables for customization -->
164 <!-- * Variables for starting ESS:: Variables for starting ESS -->
165 <!-- * Dump file variables:: Variables for dump files -->
166 <!-- * Indentation variables:: Variables controlling indentation -->
167 <!-- * Variables controlling interaction:: Variables controlling interaction -->
168 <!-- with the ESS process -->
169 <!-- @end detailmenu -->
170 </ul>
172 <!-- node-name, next, previous, up -->
174 <p><hr>
180 </div>
185 The S family (S, Splus and R) and SAS statistical analysis packages
186 provide sophisticated statistical and graphical routines for manipulating
188 of two pre-cursors, S-mode and SAS-mode, which provided support for the
189 S family and SAS respectively. Later on, Stata-mode was also incorporated.
191 <p>ESS provides a common, generic, and useful interface, through emacs, to
192 many statistical packages. It currently supports the S family, SAS, BUGS,
193 Stata and XLisp-Stat with the level of support roughly in that order.
200 (the connection between emacs and the running process) referred to as inferior ESS
202 <code>dialect</code> can take values such as <code>S3</code>, <code>S4</code>, <code>S+3</code>,
203 <code>S+4</code>, <code>S+5</code>, <code>S+6</code>, <code>S+7</code>, <code>R</code>, <code>XLS</code>, <code>VST</code>, <code>SAS</code>.
206 where actually any supported (statistics) language is meant, i.e., `S'
207 could also mean `XLisp-Stat' or `SAS'.
210 <a name="index-using-S-interactively-3"></a>For exclusively interactive users of S, ESS provides a number of
211 features to make life easier. There is an easy to use command history
212 mechanism, including a quick prefix-search history. To reduce typing,
213 command-line completion is provided for all S objects and “hot
214 keys” are provided for common S function calls. Help files are
215 easily accessible, and a paging mechanism is provided to view them.
216 Finally, an incidental (but very useful) side-effect of ESS is that a
217 transcript of your session is kept for later saving or editing.
219 <p><a name="index-transcripts-of-S-sessions-4"></a>No special knowledge of Emacs is necessary when using S
220 interactively under ESS.
222 <p><a name="index-programming-in-S-5"></a>For those that use S in the typical edit–test–revise cycle when
223 programming S functions, ESS provides for editing of S functions
224 in Emacs edit buffers. Unlike the typical use of S where the editor
225 is restarted every time an object is edited, ESS uses the current Emacs
226 session for editing. In practical terms, this means that you can edit
227 more than one function at once, and that the ESS process is still
228 available for use while editing. Error checking is performed on
229 functions loaded back into S, and a mechanism to jump directly to the
230 error is provided. ESS also provides for maintaining text versions of
231 your S functions in specified source directories.
237 <li><a accesskey="4" href="#Latest-version">Latest version</a>: Getting the latest version of ESS
239 </ul>
241 <!-- node-name, next, previous, up -->
243 <p><hr>
249 </div>
253 <p>Statistical packages are powerful software systems for manipulating and
254 analyzing data, but their user interfaces often leave something something
255 to be desired: they offer weak editor functionality and they differ
256 among themselves so markedly that you have to re-learn how to do those
257 things for each package. ESS is a package which is designed to make
258 editing and interacting with statistical packages more uniform,
259 user-friendly and give you the power of emacs as well.
261 <p>ESS provides several features which make it easier to interact with the
262 ESS process (a connection between your buffer and the statistical
263 package which is waiting for you to input commands). These include:
265 <ul>
267 entered. The `<samp><span class="samp">-e</span></samp>' flag for S-plus provides something similar to
268 this, but here you have the full range of Emacs commands rather than a
269 limited subset. However, other packages such as XLisp-Stat and S3 do not
270 necessarily have features like this built-in.
274 commands. This provides all the features of the `<samp><span class="samp">Splus -e</span></samp>' history
275 mechanism, plus added features such as history searching.
280 also applies to object names and list components.
288 S session.
292 help files.
295 </ul>
297 <p>If you commonly create or modify S functions, you will have found
298 the standard facilities for this (the `<samp><span class="samp">fix()</span></samp>' function, for
299 example) severely limiting. Using S's standard features, one can only
300 edit one function at a time, and you can't continue to use S while
301 editing. ESS corrects these problems by introducing the following
302 features:
304 <ul>
306 simultaneously in dedicated Emacs buffers. The ESS process may
307 continue to be used while functions are being edited.
311 indentation and highlighting.
315 keystroke to jump straight to the position of an error in a source file.
319 versions of S source files.
323 files, or line-by-line evaluation of files (useful for debugging).
325 </ul>
327 <p>Finally, ESS provides features for re-submitting commands from saved
328 transcript files, including:
330 <ul>
332 unnecessary prompts.
335 </ul>
337 <!-- node-name, next, previous, up -->
339 <p><hr>
345 </div>
350 <ul>
352 changing its value in <samp><span class="file">~/.emacs</span></samp> now does have the desired effect.
354 which controls whether font-locking is enabled in ESS buffers.
357 a more consistent handling of SAS options by
360 </ul>
363 <ul>
364 <li><acronym>ESS</acronym>: for XEmacs, using “gnuclient” (without a “-q”) works for
365 things like fix() after M-x gnuserv-start has been done.
367 Windows, e.g., when R has been installed in a non-default "ProgramFiles"
368 directory tree. In these cases, there's no need to specify the name (and
369 full path) of the R program anymore.
371 </ul>
374 <ul>
375 <li><acronym>ESS[R]</acronym> a new defun is available, <kbd>M-x R-newest</kbd>, which will start
376 the newest version of R that it can find on your system.
382 ess-r-args-electric-paren nil)</code> to turn it off. Further,
384 <li><acronym>ESS</acronym>: functions <code>ess-get-pdf-viewer</code> and *-ps-viewer; built on new
389 pdflatex was ok
391 none is running.
393 is only one.
394 </ul>
397 <ul>
399 new default of CHM help files on windows.
401 <li>miscellaneous fixes
402 </ul>
405 <ul>
409 set to true (which changes default behavior) such that execution or
410 help *frames* are reused.
411 </ul>
414 <ul>
415 <li>Classic BUGS now supported by <code>(require 'essd-bugs)</code> with <acronym>ESS[BUGS]</acronym>
417 of them can be used at a time since they don't play nice together. Also,
419 (<kbd>F12</kbd> has been retired). And finally, note that <samp><span class="file">essl-bug.el</span></samp>
423 <li><acronym>ESS[S]</acronym> No longer mess with .Last.value (nor in other “languages”).
424 </ul>
427 <ul>
430 <li>by uncommenting the XEmacs part of
431 Section 1 of <samp><span class="file">Makeconf</span></samp> and performing <code>make install</code>
432 <li>by unpacking either
433 <samp><span class="file">ess-5.3.1.tgz</span></samp> or <samp><span class="file">ess-5.3.1.zip</span></samp> into
436 </ol>
443 </ul>
446 <ul>
447 <li><acronym>ESS[BUGS]</acronym>: sanely re-format statistical output, <samp><span class="file">.bog</span></samp>,
448 from scientific notation to numbers rounded with 4 decimal places
450 <li>The keys for navigating among section headings in help buffers
451 worked, but only for one language per session; they should now work for
452 multiple languages. (They were also broken on Windows machines.)
454 lisp code on Windows. Particularly fixed behavior in help mode with S-plus
455 GUI.
457 which enables using the executable name instead of the dialect name for
458 R. Feature request.
460 now also works correctly when there is more than one window *side-by-side*
461 in the same frame and runs in the correct buffer also when there is more
462 than one S buffer.
463 <li>i<acronym>ESS[S]</acronym><!-- /@w --> new functions <code>ess-eval-paragraph-and-step</code> and
469 </ul>
472 <ul>
473 <li><acronym>ESS[SAS]</acronym>: <kbd>M-;</kbd> fixed, but the XEmacs function <code>comment-dwim</code>
475 uncomment-region</kbd> instead; only valid PROCs are fontified which is very
476 helpful finding syntax errors (currently supported: BASE, ETS, FSP, GRAPH,
478 empty buffer when the requested destination is a file that does not exist
479 has been fixed, now the request results in a no-op.
480 Further, sas-mode now also works in simple terminals.
481 <li>Rterm/Cygwin combination works under Microsoft Windows.
483 define 'baseenv' where needed.
484 <li>New experimental support for installing ESS. See the file
486 </ul>
489 <ul>
490 <li>ESS Info entry and <samp><span class="file">dir</span></samp> handled more effectively for GNU Emacs users
494 <li>iESS[SAS]: fixed a few nagging bugs, however, still does not appear to
495 work at this time; please let us know if you have any ideas.
499 Splus you would like to run.
500 </ul>
503 <ul>
505 customization was not taking effect unless customizations were loaded
506 before ESS). Its value has been changed so that it will also find R
508 change this variable, it must be set in your <samp><span class="file">.emacs</span></samp> before ESS is
509 loaded.
510 <li>Installation with GNU Make enhanced: unix and unix-like
512 users in either a GNU Emacs site-lisp or an XEmacs package
513 configuration by editing <samp><span class="file">lisp/ess-site.el</span></samp> and <samp><span class="file">Makeconf</span></samp>
516 XEmacs for R and S-plus.
517 <!-- working around a bug in XEmacs -->
518 </ul>
521 <ul>
523 with respect to ess-load-file has been eradicated.
524 <li>i<acronym>ESS[SAS]</acronym><!-- /@w -->: <kbd>C-c C-r</kbd> and <kbd>C-c C-b</kbd> once again
525 work as intended and documented.
530 cases, including S4 method definitions.
534 were being treated as bogus.
537 buffer is not bogus, but instead is now relabelled “*help[R](rlm in
538 packages)*”.
539 <li><acronym>ESS[STA]</acronym>: add “//” as comment starting character to syntax-table.
540 </ul>
543 <ul>
546 </ul>
549 <ul>
550 <li>If you use Custom to change the variable ess-toolbar-items,
551 the new toolbar is used in all subsequent ESS buffers.
553 your .log grows to more than ess-sas-log-max bytes, just
554 the first ess-sas-log-max bytes are refreshed; this is helpful when your .sas program
555 generates lots of error messages and gets too big for emacs to display
557 either one or two hashes depending on context.
559 are now available (from ess-swv.el loaded by default).
560 </ul>
563 <ul>
564 <li>Removed non-ASCII characters in a few files.
566 particular, you get correct directional quotes in R's startup message
567 for R-devel (unstable development version of R 2.1.0) when using
568 environment variables LANGUAGE=en@quot LC_ALL=en_US.UTF-8
575 e.g., for "_"; both now fontify warning(.) and S does terminate() additionally.
576 <li>Support for `bell' aka `beep' aka `ding' aka `alarm' in all inferior
578 the bell is rung.
579 </ul>
582 <ul>
583 <li><acronym>ESS[R]</acronym>: <kbd>C-c C-q</kbd> or `<samp><span class="samp">Quit S</span></samp>' from the menu now should work
584 (again and less klunkily) and do not append `<samp><span class="samp">-exited</span></samp>' to the
586 ess-quit, now depends on the new customizable variable
593 </ul>
596 <ul>
597 <li>The documentation now includes an overview of how to use the emacs
598 TAGS facility for S functions. (The distribution also used to contain a
599 directory <samp><span class="file">etc/other/Tags</span></samp> where a ~1990 version of <samp><span class="file">etags.c</span></samp> was
600 distributed; this is no longer relevant and so has been deleted.)
602 platform, .log NOTEs may display as gibberish since the EBCDIC
603 characters are not converted to ASCII prior to their display. So,
604 the function ess-ebcdic-to-ascii-search-and-replace is provided for
607 <li>ESS: Completion of object names is now always done dynamically rather
608 than allowing the option of using a pre-computed database (by
610 enough for dynamic completion. (We expect few users, if any, have
611 been using the pre-computed database method.)
612 <li>ESS: object completion in iESS buffers running on Windows was
613 very slow (for GNU Emacs, but not XEmacs) and has now been fixed.
614 Further, it was more or less broken for all versions of S-plus 6.x,
615 and has been fixed to work everywhere but with the Windows' GUI of
616 S-plus. The list of objects now shows unique names also when an
617 object appears more than once in the search path.
620 </ul>
623 <ul>
624 <li>ESS: When new inferior ESS processes are created, by default they
625 will replace the current buffer (this restores behavior from pre
626 5.2.0). If you wish new ESS processes to start in another window of the
627 current frame, set inferior-ess-same-window to nil.
628 <li>New variables inferior-Splus-args and inferior-R-args provide a
629 way to pass command line arguments to starting S and R processes.
630 </ul>
633 <ul>
635 <li>ess-lisp-directory/../doc/info added to Info-directory-list
636 if ess-info not found by info
639 ESS will find them and create appropriate functions, such as
641 By default only Unix programs beginning "R-1" and
642 "R-2" and Windows programs parallel to the
643 version of R in your exec-path will be found,
644 but see ess-r-versions and ess-rterm-versions for ways to find other
645 versions of R.
647 Windows, are added to the
648 "ESS / Start Process / Other" menu.
652 inside an emacs buffer. By default only
653 programs installed in the default location will be found, but see
654 ess-SHOME-versions for ways to find other versions of S-Plus.
656 are added to the
657 "ESS / Start Process / Other" menu.
658 <li><acronym>ESS[R]</acronym>: (bug fix) ess-quit (bound to <kbd>C-c C-q</kbd>) should now quit the
659 inferior R process, when issued from either the inferior buffer, or from
660 a .R buffer.
661 </ul>
664 <ul>
666 with icons to evaluate code in the inferior process or to switch
667 there. This code is experimental and likely to change as XEmacs/Emacs
668 issues get resolved. The toolbar should be enabled if your Emacs
669 displays images, but can be disabled with the variable ess-use-toolbar.
670 Thanks to David Smith from Insightful for the S-plus logo.
672 external file viewers for each graphics file type via the alist
673 ess-sas-graph-view-viewer-alist; also .jpg/.gif are now handled
674 by image-mode on XEmacs, if available, otherwise by graphics
675 primitives as before
676 </ul>
679 <ul>
682 new architecture-independent unix support as well as support for BUGS v. 0.5
684 info documentation improved; Local Variable bug fixes;
685 SAS/IML statements/functions now highlighted; files edited
686 remotely by ange-ftp/EFS/tramp are recognized and pressing
687 SUBMIT opens a buffer on the remote host via the local variable
688 ess-sas-shell-buffer-remote-init which defaults to "ssh";
689 changed the definition of the variable ess-sas-edit-keys-toggle
691 which automatically reverse indents lines containing only "run;";
696 <kbd>C-c C-b</kbd> for submit buffer, <kbd>C-c C-x</kbd> for goto .log; <kbd>C-c C-y</kbd> for goto .lst
698 pressing underscore twice inserts a literal underscore. To stop this
699 smart behaviour, add "(ess-toggle-underscore nil)" to your .emacs after
700 ess-site has been loaded;
701 ess-dump-filename-template-proto (new name!) now can be
702 customized successfully (for S language dialects);
703 Support for Imenu has been improved; set ess-imenu-use-S to non-nil to
704 get an "Imenu-S" item on your menubar;
705 ess-help: Now using nice underlines (instead of `nuke-* ^H_')
707 numbers from any Emacs buffer into an existing *R* process;
709 fixed ess-retr-lastvalue-command, i.e. .Last.value bug
710 (thanks to David Brahm)
711 <li>ESS: Support for creating new window frames has been added to
712 ESS. Inferior ESS processes can be created in dedicated frames by
713 setting inferior-ess-own-frame to t. ESS help buffers can also open in
714 new frames; see the documentation for ess-help-own-frame for details.
715 (Thanks to Kevin Rodgers for contributing code.)
716 </ul>
719 <ul>
720 <li>The version number is now correct even inside ESS/Emacs
721 </ul>
724 <ul>
725 <li>Minor more Makefile clean up.
726 </ul>
729 <ul>
730 <li>Besides info documentation, PDF and HTML
731 documentation are also provided (instead of built using "make") and available
732 on the web as well; see <a href="http://ess.r-project.org/">ESS web page</a> and <a href="http://lib.stat.cmu.edu/general/ESS/doc">StatLib</a>
733 <li>Now that info documentation is available, the
734 README.* files are no longer supported. However, they
735 are still distributed for what it's worth.
736 <li>ESS is now an XEmacs package! See
740 SAS batch jobs with Kermit file transfers (LOG and OUTPUT
741 function key features now supported). Multiple shells
742 now supported so you can run SAS on different computers
743 from different buffers by setting the buffer-local variable
744 ess-sas-shell-buffer to unique buffer names.
745 <li>Major re-vamping of Makefile/Makeconf.
746 </ul>
749 <ul>
752 either within emacs, when available, or via an external viewer;
753 more syntax highlighting keywords; more enhancements for remote
754 SAS batch jobs with Kermit; new framework for remote SAS interactive
755 jobs, see ess-remote
757 ESS->Help for the S family
758 <li>Makefile: tag now independent of rel; info files
759 made by doc/Makefile and installed in new info sub-directory
760 </ul>
763 <ul>
764 <li>New `options()$STERM' in the S dialects (S, S-Plus, R).
765 The S program can determine the environment in which it is
766 currently running. ESS sets the option to `iESS' or `ddeESS'
767 when it starts an S language process. We recommend other specific
768 values for S language processes that ESS does not start.
770 User may click on a word or region and then choose from the
771 menu to display the item, or a summary, or a plot, etc.
772 This feature is still under development.
774 (some from Stephen Eglen).
776 <li>XEmacs on Win (NT) is better supported.
778 <li>should now work even when imenu is not available (for old XEmacsen).
779 <li><acronym>ESS[SAS]</acronym>: XEmacs-Imenu fix; <kbd>C-TAB</kbd> is globalized along with your
780 function-key definitions, if specified; you can specify your SAS
781 library definitions outside of autoexec.sas for ess-sas-data-view
782 with SAS code placed in the variable ess-sas-data-view-libname,
783 also the dataset name is defaulted to the nearest permanent dataset
784 to point; Speedbar support now works for permanent datasets, please
785 ignore first./last.; new font-locking is now the default with more
786 improvements for font-locking PROCs, macro statements, * ; and %* ;
788 your .log (if it isn't too big); submit remote .sas files accessed
789 with ange-ftp, EFS or Tramp (Kermit is experimental) by setting
790 ess-sas-submit-method to 'sh; ess-sas-submit-command and
791 ess-sas-submit-command-options are buffer-local so you can have
792 local file variable sections at the end of your .sas files to
793 request different executables or specify special options and the
794 local file variables are re-read at submit instead of only at file
795 open so that if you make a change it is picked up immediately;
797 <li>for STATA: font-lock bug fixed.
800 by things such as \code{.}, \code{\link{.}}, \emph{.} etc.
801 <li>new functions (ess-directory-function) and (ess-narrow-to-defun)
803 <li>Re-organized Makefile and fixed a few bugs.
804 </ul>
807 <ul>
810 Templates assist you in writing .bug and .cmd code (.cmd and .log
811 are replaced by .bmd and .bog to avoid emacs extension collisions).
815 <li>Fixes for `ess-smart-underscore' SAS breakage (Rich Heiberger)
816 <li>You can change between PC and Unix, local and global SAS function-key
817 definitions interactively (Rich Heiberger)
819 <li>New and improved SAS syntax highlighting (Rodney Sparapani)
820 To get the new functionality, set ess-sas-run-make-regexp to nil.
823 You must have the library defined in autoexec.sas for it to work.
824 <li>User-friendly defaults for `sas-program', `ess-sas-batch-pre-command'
825 and `ess-sas-batch-post-command' as well Customize support for these
828 <li>Emacs/XEmacs, Unix/Windows issues collectively handled in ess-emcs.el
829 <li>defadvice solves problem of missing *ESS* (thanks to Jeff Mincy)
830 <li>Improved manual a bit by including things that were only in `README'.
831 </ul>
834 <ul>
836 Inserts `ess-S-assign' (customizable " <- "), unless inside string
837 and comments where plain "_" is used instead. (MM)
838 <li>Fixes for longstanding interactive SAS breakage (RMH)
839 </ul>
842 <ul>
843 <li>Documentation for Windows Installation (Rich Heiberger)
844 <li>removal of ess-vars, finalization of customize support (in the
845 sense that there is no more use of ess-vars, but that we need to
846 fix ess-cust) (AJ Rossini)
847 <li>Many small (and large) fixes/contributions (MMaechler)
850 customizable. (MMaechler)
851 </ul>
854 <ul>
855 <li>BUG FIXES
856 <li>Better SAS support
857 </ul>
860 <ul>
861 <li>BUG FIXES
862 </ul>
865 <ul>
866 <li>Yet more fixes to SAS mode, (Rich Heiberger and Rodney Sparapani)
867 <li>Customize support (for most Emacsen which support it) (AJRossini)
868 <li>ARC and ViSta support out of the box, and fixes for XLispStat (AJRossini)
869 </ul>
872 <ul>
873 <li>Version numbering finally all depending on the ./VERSION file,
874 thanks to Martin Maechler.
875 <li>Yet more fixes to SAS mode, thanks to Rich Heiberger.
876 </ul>
879 <ul>
881 Chuck Taylor, and others.
882 <li>More fixes to SAS mode, thanks to Rodney Sparapani
883 and Rich Heiberger.
884 </ul>
887 <ul>
888 <li>More fixes to Stata mode, thanks to
890 <li>fixed bugs in ESS-elsewhere, thanks to many testers
893 <li>Fixes to SAS mode, thanks to Rodney Sparapani
894 </ul>
897 <ul>
898 <li>More fixes to Stata mode
899 <li>primitive generic version of ESS-elsewhere
900 <li>Small fixes to SAS/Stata.
901 </ul>
904 <ul>
905 <li>Stata mode works
906 <li>Literate Data Analysis using Noweb works
907 </ul>
910 <ul>
911 <li>Bug fixes
912 <li>R documentation mode defaults changed
913 </ul>
916 <ul>
917 <li>able to use inferior iESS mode to
918 communicate directly with a running S-Plus 4.x process using the
920 and related key sequences to send lines from the S-mode file to the
922 and transcripts of previous S sessions in ESS Transcript mode. All
923 three modes know the S language, syntax, and indentation patterns and
924 provide the syntactic highlighting that eases the programming tasks.
925 </ul>
927 <!-- node-name, next, previous, up -->
929 <p><hr>
935 </div>
940 The ESS environment is built on the open-source projects of many
941 contributors, dating back to 1989 where Doug Bates and Ed Kademan wrote
942 S-mode to edit S and Splus files in GNU Emacs. Frank Ritter and Mike
943 Meyer added features, creating version 2. Meyer and David Smith made
945 provided significant enhancements to allow for powerful process
946 interaction.
949 Cook added functions to submit jobs, review listing and log files, and
950 produce basic views of a dataset, thus creating a SAS-mode which was
951 distributed in 1994.
954 with extensions written by Martin Maechler, this became version 4.7
955 and supported S, Splus, and R. In 1995, Rossini extended SAS-mode to
956 work with XEmacs.
959 package for statistical programming; the product of this marriage was
960 called ESS version 5. Richard M. Heiberger designed the inferior mode
961 for interactive SAS and SAS-mode was further integrated into ESS.
962 Thomas Lumley's Stata mode, written around 1996, was also folded into
963 ESS. More changes were made to support additional statistical
964 languages, particularly XLispStat.
966 <p>ESS initially worked only with Unix statistics packages that used
967 standard-input and standard-output for both the command-line interface
968 and batch processing. ESS could not communicate with statistical
969 packages that did not use this protocol. This changed in 1998 when
970 Brian Ripley demonstrated use of the Windows Dynamic Data Exchange
971 (DDE) protocol with ESS. Heiberger then used DDE to provide
972 interactive interfaces for Windows versions of Splus. In 1999, Rodney
973 A. Sparapani and Heiberger implemented SAS batch for ESS relying
974 on files, rather than standard-input/standard-output, for Unix,
975 Windows and Mac. In 2001, Sparapani added BUGS batch file processing
976 to ESS for Unix and Windows.
978 <ul>
979 <li>The multiple process code, and the idea for
982 <li>Thanks to Doug Bates for many useful suggestions.
984 <li>Thanks to Martin Maechler for reporting and fixing bugs, providing many
985 useful comments and suggestions, and for maintaining the ESS mailing
986 lists.
988 <li>Thanks to Frank Ritter for updates, particularly the menu code, and
989 invaluable comments on the manual.
991 <li>Thanks to Ken'ichi Shibayama for his excellent indenting code, and many
992 comments and suggestions.
994 <li>Thanks to Aki Vehtari for adding interactive BUGS support.
996 <li>Thanks to Brendan Halpin for bug-fixes and updates to Stata-mode.
998 <li>Last, but definitely not least, thanks to the many ESS users and
999 contributors to the ESS mailing lists.
1000 </ul>
1004 <ul>
1007 <!-- -->
1010 <!-- -->
1013 <!-- -->
1016 <!-- -->
1019 <!-- -->
1022 </ul>
1024 <!-- node-name, next, previous, up -->
1026 <p><hr>
1032 </div>
1036 <p>The latest released version of ESS is always available on the web at:
1040 <!-- There no longer is an anonymous CVS repository for ESS, due to lack of -->
1041 <!-- interest, little demand, and problems with security. -->
1042 <!-- text below modified from R-admin.texi (thanks to Kurt for the tip). -->
1043 <p>The latest development version of ESS is available via
1044 <a href="https://svn.R-project.org/ESS/">https://svn.R-project.org/ESS/</a>, the ESS Subversion repository. If
1045 you have a Subversion client (see <a href="http://subversion.tigris.org/">http://subversion.tigris.org/</a>),
1046 you can download the sources using:
1048 </pre>
1050 within that directory, `svn update' will bring that directory up to
1051 date. Windows-based tools such as TortoiseSVN are also available for
1052 downloading the files. Alternatively, you can browse the sources with a
1053 web browser at: <a href="https://svn.r-project.org/ESS/trunk">ESS SVN site</a>. However, please use a subversion client instead to minimize the
1054 load when retrieving.
1056 <p>If you remove other versions of ESS from your emacs load-path, you can
1057 then use the development version by adding the following to .emacs:
1060 </pre>
1061 <p>Note that https is required, and that the SSL certificate for the
1062 Subversion server of the R project is
1065 - Hostname: svn.r-project.org
1067 - Issuer: Department of Mathematics, ETH Zurich, Zurich, Switzerland, CH
1069 </pre>
1070 <p class="noindent">(currently, there is no “trusted certificate”). You can accept this
1071 certificate permanently and will not be asked about it anymore.
1073 <!-- node-name, next, previous, up -->
1075 <p><hr>
1080 </div>
1084 <p>If you need to install ESS, read <a href="#Installation">Installation</a> for details on what
1085 needs to be done before proceeding to the next chapter.
1087 <p>In this manual we use the standard notation for describing the
1091 META, EDIT or ALT key, instead press and release the ESC key and then
1095 the useful commands are bound to keystrokes for ease of use. Also, the
1096 most popular commands are also available through the emacs menubar, and
1097 finally, if available, a small subset are provided on the toolbar.
1098 Where possible, keybindings are similar to other modes in emacs to
1099 strive for a consistent user interface within emacs, regardless of the
1100 details of which programming language is being edited, or process being
1101 run.
1106 be asked for command line options that you wish to invoke the R process
1107 with.
1109 <p>Emacs is often referred to as a `self-documenting' text editor. This
1110 applies to ESS in two ways. First, limited documentation about each ESS
1113 in a separate *Help* buffer. Second, a complete list of keybindings
1114 that are available in each ESS mode and brief description of that mode
1117 <p>Emacs is a versatile editor written in both C and lisp; ESS is written
1118 in the Emacs lisp dialect (termed `elisp') and thus benefits from the
1119 flexible nature of lisp. In particular, many aspects of ESS behaviour
1120 can be changed by suitable customization of lisp variables. This manual
1121 mentions some of the most frequent variables. A full list of them
1122 however is available by using the Custom facility within emacs. (Type
1125 change to customize ESS to your taste, but it is recommended that you
1126 defer this section until you are more familiar with ESS.
1128 <!-- node-name, next, previous, up -->
1130 <p><hr>
1136 </div>
1141 The following section details those steps necessary to get ESS running
1142 on your system.
1145 <li><a accesskey="1" href="#Unix-installation">Unix installation</a>: Installing ESS on your Unix system
1146 <li><a accesskey="2" href="#Microsoft-Windows-installation">Microsoft Windows installation</a>: Installing ESS on your MS Windows system
1147 <li><a accesskey="3" href="#Requirements">Requirements</a>: emacs, Operating Systems and Statistical Packages
1148 </ul>
1150 <!-- FIXME: the following contains @node s *and* is also included by readme.texi -->
1151 <!-- which does *not* include 'requires.texi' -->
1152 <!-- ==> *must* give node pointer problems! -->
1154 <p><hr>
1156 Next: <a rel="next" accesskey="n" href="#Microsoft-Windows-installation">Microsoft Windows installation</a>,
1159 </div>
1161 <!-- node-name, next, previous, up -->
1166 <li>
1168 new directory (for example, <samp><span class="file">$HOME/emacs</span></samp>) to hold the distribution.
1169 This directory will be referred to below as "the ESS distribution
1170 directory".
1173 But, you can still install ESS into the XEmacs package system by choosing
1174 <samp><span class="file">ESSDIR</span></samp>=<samp><span class="file">PREFIX/lib/xemacs/site-packages</span></samp>.
1175 ESS requires that the XEmacs sumo tarball (all XEmacs packages combined) also
1176 be installed. For information on installing XEmacs packages, follow this link:
1179 <!-- It will contain, -->
1180 <!-- at the end, the tar file @file{ess-VERSION.tar.gz}, and a directory for -->
1181 <!-- the ESS source, which will be termed "the ESS-VERSION source directory". -->
1182 <!-- Note that the .elc files may be installed elsewhere (as specified in the -->
1183 <!-- Makefile) if desired. -->
1184 <li>Retrieve the latest version from
1188 <li>Extract the files from the disribution.
1191 </pre>
1192 <p>The <code>tar</code> command will create the subdirectory <samp><span class="file">ess-VERSION</span></samp> and install
1193 the files there.
1195 <!-- If you are using GNU Emacs 19.29, decompress/unarchive -->
1196 <!-- @file{ESSDIR/ess-VERSION/lisp/19.29.tar.gz}, -->
1197 <!-- read @file{ESSDIR/ess-VERSION/lisp/19.29/README}, follow the instructions -->
1198 <!-- and you might be able to get ESS to work. -->
1199 <!-- @emph{Please note that GNU Emacs 19.29 is no longer supported}. -->
1200 <!-- For a list of supported versions of emacs, see @xref{Requirements}. -->
1201 <li>Edit the file <samp><span class="file">ESSDIR/ess-VERSION/lisp/ess-site.el</span></samp> as explained in the
1202 comments section of that file.
1203 <!-- Installations that are using ESS only for S-Plus -->
1204 <!-- 6.x will probably not need to make any changes. Installations that also -->
1205 <!-- have one or more of (S4, S+3/4/5/6/7/8, R, SAS, BUGS, XLispStat, Stata) -->
1206 <!-- may need to uncomment corresponding lines in @file{ESSDIR/ess-VERSION/lisp/ess-site.el}. -->
1208 <li>If you are using GNU Emacs add the line
1210 </pre>
1211 <p>to <samp><span class="file">$HOME/.emacs</span></samp>. For XEmacs, if you followed the XEmacs package system
1212 installation advice, add the line
1214 </pre>
1215 <p>to <samp><span class="file">$HOME/.xemacs/init.el</span></samp>. Otherwise, for XEmacs, add the line
1217 </pre>
1220 <!-- GNU Emacs uses @file{default.el} or -->
1221 <!-- @file{site-init.el} and XEmacs uses @file{site-start.el} for the system -->
1222 <!-- installation file). -->
1223 <!-- Alternatively, if @file{ess-site.el} is in your current @code{load-path}, then: -->
1224 <!-- @example -->
1225 <!-- (require 'ess-site) -->
1226 <!-- @end example -->
1227 <!-- to configure emacs for ESS. -->
1228 <li>That's it! ESS is now ready to use. (The remaining step below is only for a
1229 custom installation.) To edit statistical programs, just open files with the
1230 requisite extensions (<samp><span class="file">.R</span></samp> for R, <samp><span class="file">.sas</span></samp> for SAS, <samp><span class="file">.bug</span></samp> for BUGS,
1233 <!-- @item -->
1234 <!-- (OPTIONAL) If you are running S-PLUS or R, you might consider -->
1235 <!-- installing the database files. From within emacs, @code{C-x d} to the -->
1236 <!-- directory containing ESS. Now: -->
1237 <!-- @example -->
1238 <!-- M-x S+6 -->
1239 <!-- @end example -->
1240 <!-- to get S running. Once you see the SPLUS prompt, do: -->
1241 <!-- @example -->
1242 <!-- M-x ess-create-object-name-db -->
1243 <!-- @end example -->
1244 <!-- (this will create the file @file{ess-sp6-namedb.el}; if it isn't in the -->
1245 <!-- ESS directory, move it there). -->
1246 <!-- Then, completions will be autoloaded and will not be regenerated for -->
1247 <!-- every session. -->
1248 <!-- For R, do the same, using -->
1249 <!-- @example -->
1250 <!-- M-x R -->
1251 <!-- @end example -->
1252 <!-- and then @code{M-x ess-create-object-name-db} creating -->
1253 <!-- @file{ess-r-namedb.el}; if it isn't in the ESS directory, move it there). -->
1256 <p>If you want to place the compiled files in other locations edit the
1258 <samp><span class="file">Makeconf</span></samp> in the <samp><span class="file">ESSDIR/ess-VERSION</span></samp> directory (if you are
1259 using XEmacs, then uncomment the XEmacs subsection in Section 1).
1261 <p>You can compile those files by:
1263 </pre>
1264 <p>When that completes successfully, install the compiled files:
1266 </pre>
1267 <!-- This will install the compiled info files and lisp files. If you are an -->
1268 <!-- XEmacs user, then you should be done. If not, then you may have to -->
1269 <!-- edit/create the file @file{dir} that is found in the directory specified -->
1270 <!-- by @code{INFODIR}: see the sample @file{dir} in ESSDIR/ess-VERSION/doc/info. -->
1271 <!-- If @file{dir} does not exist in @code{INFODIR}, then the sample -->
1272 <!-- @file{dir} will be installed. -->
1273 <!-- An alternative, if you are running XEmacs and have access to the -->
1274 <!-- XEmacs system directories, would be to place the directory in the -->
1275 <!-- site-lisp directory, and simply type @code{make all} (and copy the -->
1276 <!-- documentation as appropriate). -->
1277 <!-- For GNU Emacs, you would still have to move the files into the top level -->
1278 <!-- site-lisp directory. -->
1279 </ol>
1281 <!-- >>>> FIXME (see comment in ess.texi): error in ``makeinfo readme.texi'' -->
1282 <!-- @node Microsoft Windows installation, , Unix installation, Installation -->
1284 <p><hr>
1287 Previous: <a rel="previous" accesskey="p" href="#Unix-installation">Unix installation</a>,
1290 </div>
1292 <!-- node-name, next, previous, up -->
1300 new directory (for example, <samp><span class="file">c:\emacs\</span></samp>) to hold the distribution.
1301 This directory will be referred to below as "the ESS distribution
1302 directory".
1305 package. But, you can still install ESS into the XEmacs package system
1306 by choosing <samp><span class="file">ESSDIR</span></samp>=<samp><span class="file">PREFIX\XEmacs\site-packages</span></samp>. ESS
1307 requires that the XEmacs sumo tarball (all XEmacs packages combined)
1308 also be installed. For information on installing XEmacs packages,
1309 follow this link:
1314 store it in the ESS distribution directory. Be aware that http browsers
1316 other punctuation. Please change the names back to their original form.
1318 <li>Extract all the files from <samp><span class="file">ess-VERSION.zip</span></samp> into the ESS
1319 distribution directory as <samp><span class="file">c:\emacs\ess-VERSION\</span></samp>. (It is possible
1320 to unpack the zip archive in Windows Explorer by double clicking on the
1321 folder; you should then see a new folder called <samp><span class="file">ess-VERSION</span></samp>.
1322 Drag that folder into your ESS distribution directory.)
1324 <!-- @item -->
1325 <!-- Add the line -->
1326 <!-- @example -->
1327 <!-- (load "C:/emacs/ess-VERSION/lisp/ess-site") -->
1328 <!-- @end example -->
1329 <!-- to your emacs initialization file. (GNU Emacs uses the filename -->
1330 <!-- @file{~/.emacs} and XEmacs uses the filename -->
1331 <!-- @file{~/.xemacs/init.el} for the initialization file. The tilde is -->
1332 <!-- recognised by emacs as your HOME directory, i.e. the value of your HOME -->
1333 <!-- environment variable.) Replace -->
1334 <!-- @code{VERSION} above with the version number of ESS. Remember to use -->
1335 <!-- forwardslashes @code{/}, rather than backslashes @code{\}, in your filename -->
1336 <!-- inside emacs code files. -->
1337 <li>If you are using GNU Emacs add the line
1339 </pre>
1340 <p>to <samp><span class="file">%HOME%/.emacs</span></samp>. For XEmacs, if you followed the XEmacs package system
1341 installation advice, add the line
1343 </pre>
1344 <p>to <samp><span class="file">%HOME%/.xemacs/init.el</span></samp>. Otherwise, for XEmacs, add the line
1346 </pre>
1349 variable be set on your system, otherwise, your initialization file will
1350 not be utilized, and therefore, ESS will not work.
1352 <p>After saving your initialization file, ESS is now installed. Start a
1353 new emacs and you should be ready to use ESS. For example, to edit
1354 statistical programs, load the files with the requisite extensions
1356 R, and ".lsp" for XLispStat). One further step is needed if you wish to
1357 run statistical processes, see below.
1359 <li>To run statistical processes under ESS, Windows users will need to make
1360 sure that the directories for the software they will be using is in the
1361 PATH environment variable. On Windows 9x, add lines similar to the
1364 </pre>
1367 Note that the directory containing the program is
1368 added to the PATH, not the program itself. One such line is needed
1369 for each software program. Be sure to use the abbreviation
1371 backslashes "<code>\</code>".
1373 <p>An alternative, for R users, is that rather than adjusting the PATH
1374 variable, you can add the following to your emacs initialization file
1375 (and restart emacs):
1377 </pre>
1379 Change the path otherwise to point to other locations.
1381 <p>Windows users who place S-PLUS anywhere other than the default
1382 location will also need to add the following three lines (properly
1386 "c:/progra~1/Insightful/SPLUS70/cmd/Splus")
1387 (setq-default inferior-Sqpe+6-SHOME-name
1388 "c:/progra~1/Insightful/SPLUS70")
1389 (setq-default inferior-Sqpe+6-program-name
1390 "c:/progra~1/Insightful/SPLUS70/cmd/Sqpe.exe")
1391 </pre>
1392 <p>The above example uses the default location of S-PLUS in
1397 to match their installation in order to get the full set of S-PLUS versions
1402 <li>If you use Cygwin bash as your primary shell, then
1405 </pre>
1406 <li>If you use the MSDOS prompt window as your primary shell, then
1408 </pre>
1409 </ol>
1410 You will then be
1411 asked for a pathname ("S starting data directory?"), from which to
1412 start the process. The prompt will propose your current directory
1413 as the default. ESS will start the S-PLUS GUI. There will be
1414 slight delay during which emacs is temporarily frozen. ESS will arrange for
1415 communication with the S-PLUS GUI using the DDE protocol.
1416 Send lines or regions
1417 from the emacs buffer containing your S program (for example,
1424 without the S-PLUS GUI:
1427 </pre>
1428 <p>This works with both the bash and msdos shells.
1429 You will then be asked for a pathname ("S starting data
1430 directory?"), from which to start the process. The prompt will
1431 propose your current directory as the default.
1432 You get Unix-like behavior, in particular the entire
1433 transcript is available for emacs-style search commands.
1434 Send lines or regions from the emacs buffer containing your S
1435 program (for example, <samp><span class="file">myfile.s</span></samp>) to the *S+6* buffer with the
1437 Interactive graphics are available with Sqpe by using the java
1438 library supplied with S-PLUS 6.1 and newer releases.
1439 Enter the commands:
1441 java.graph()
1442 </pre>
1444 in several formats, but not PostScript. If you
1445 need a PostScript file you will need to open a separate
1449 <p>To connect to an already running S-PLUS GUI (started, for example,
1450 from the S-PLUS icon):
1452 </pre>
1453 <p>or
1455 </pre>
1456 <p>You will then be
1457 asked for a pathname ("S starting data directory?"), from which to
1458 start the process. The prompt will propose your current directory
1459 as the default. ESS will arrange for
1460 communication with the already running S-PLUS GUI using the DDE protocol.
1461 Send lines or regions
1462 from the emacs buffer containing your S program (for example,
1468 <p>If you wish to run R, you can start it with:
1470 </pre>
1471 <p>XLispStat can not currently be run with
1473 </pre>
1474 <p>Hopefully, this will change. However, you can still edit with
1475 emacs, and cut and paste the results into the XLispStat
1476 *Listener* Window under Microsoft Windows.
1478 <!-- SAS for Windows uses the batch access with function keys that is -->
1479 <!-- described in -->
1480 <!-- @file{doc/README.SAS}. -->
1481 <!-- @xref{ESS(SAS)-MS Windows}. -->
1482 <!-- The user can also edit SAS files -->
1483 <!-- in an @code{ESS[SAS]} buffer and than manually copy and paste them into -->
1484 <!-- an Editor window in the SAS Display Manager. -->
1485 <!-- For Windows, inferior SAS in an @code{iESS{[SAS]}} buffer does not work -->
1486 <!-- on the local machine. It does work over a network connection to -->
1487 <!-- SAS running on a remote Unix computer. -->
1488 <!-- Reason: we use ddeclient to interface with programs and SAS doesn't -->
1489 <!-- provide the corresponding ddeserver capability. -->
1490 <!-- @item -->
1491 <!-- (OPTIONAL) If you are running Sqpe or R, you might consider -->
1492 <!-- installing the database files. From within emacs, @code{C-x d} to -->
1493 <!-- the directory containing ESS. Now: -->
1494 <!-- @example -->
1495 <!-- M-x Sqpe+6 -->
1496 <!-- @end example -->
1497 <!-- to get S running. Once you see the SPLUS prompt, do: -->
1498 <!-- @example -->
1499 <!-- M-x ess-create-object-name-db -->
1500 <!-- @end example -->
1501 <!-- (this will create the file @file{ess-s+6-namedb.el}; if it isn't in the -->
1502 <!-- ESS directory, move it there). -->
1503 <!-- Then, completions will be autoloaded and will not be regenerated -->
1504 <!-- for every session. -->
1505 <!-- For R, do the same, using -->
1506 <!-- @example -->
1507 <!-- M-x R -->
1508 <!-- @end example -->
1509 <!-- and then @code{M-x ess-create-object-name-db} creating -->
1510 <!-- @file{ess-r-namedb.el}; if it isn't in the ESS directory, move it -->
1511 <!-- there). -->
1512 <li>That's it!
1514 </ol>
1515 <!-- Requirements duplicated? -->
1516 <!-- @node Requirements, , Microsoft Windows installation, Installation -->
1517 <!-- node-name, next, previous, up -->
1518 <!-- @section Requirements -->
1519 <!-- @include requires.texi -->
1522 <p><hr>
1524 Previous: <a rel="previous" accesskey="p" href="#Microsoft-Windows-installation">Microsoft Windows installation</a>,
1527 </div>
1529 <!-- node-name, next, previous, up -->
1532 <p>ESS has been tested with
1534 <ul>
1537 <li>S4
1542 <!-- is anyone still using this? @item XLispStat >=3.50 -->
1543 </ul>
1545 <p>on the following platforms
1547 <ul>
1548 <li>Linux/x86 (all)
1549 <li>Solaris/SPARC (all)
1550 <!-- cannot confirm this right now @item SGI (all) -->
1551 <li>MS Windows 98/NT/2000/XP (R, SPLUS 4.5/2000/6.0-2/7.0/8.0, SAS interactive only, and BUGS 0.6)
1553 </ul>
1555 <p>with the following versions of emacs
1557 <ul>
1559 <li>XEmacs 21.4.0-8, 21.4.9-13<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>, 21.4.14-15, 21.4.17-21 (betas not supported, but 21.5.23+ may work)
1560 <!-- @item GNU Emacs <20.3 and XEmacs <21.0@footnote{These releases of emacs are no -->
1561 <!-- longer supported, so an upgrade is recommended if you plan to use ESS. -->
1562 <!-- If you have GNU Emacs 19.29, see @xref{Unix installation}. Also, note -->
1563 <!-- that the `custom' library bundled with Emacs 19.34 is too _old_, its API is -->
1564 <!-- incompatible with the `new custom' bundled with recent Emacsen. -->
1565 <!-- The `new custom' for Emacs 19.34 is available for download -->
1566 <!-- @uref{ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz, here}.} -->
1567 </ul>
1569 <!-- node-name, next, previous, up -->
1571 <p><hr>
1577 </div>
1581 <p>As well as using ESS to edit your source files for statistical programs,
1582 you can use ESS to run these statistical programs. In this chapter, we
1583 mostly will refer by example to running S from within emacs. The emacs
1584 convention is to name such processes running under its control as
1585 `inferior processes'. This term can be slightly misleading, in which
1586 case these processes can be thought of `interactive processes'. Either
1587 way, we use the term `iESS' to refer to the Emacs mode used to interact
1588 with statistical programs.
1590 <!-- node-name, next, previous, up -->
1594 <li><a accesskey="3" href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a>
1595 <li><a accesskey="4" href="#S_002belsewhere-and-ESS_002delsewhere">S+elsewhere and ESS-elsewhere</a>
1597 </ul>
1600 <p><hr>
1602 Next: <a rel="next" accesskey="n" href="#Multiple-ESS-processes">Multiple ESS processes</a>,
1606 </div>
1611 To start an S session on Unix or on Windows when you
1614 <p>To start an S session on Windows when you
1618 <a name="index-ESS-process-directory-13"></a><a name="index-starting-directory-14"></a><a name="index-working-directory-15"></a><a name="index-directories-16"></a>
1619 S will then (by default) ask the question
1621 </pre>
1624 the shell). This directory should have a <samp><span class="file">.Data</span></samp> subdirectory.
1626 <p>You will then be popped into a buffer
1627 <a name="index-ESS-process-buffer-17"></a><a name="index-process-buffer-18"></a>with name `<samp><span class="samp">*S*</span></samp>' which will be used
1628 for interacting with the ESS process, and you can start entering commands.
1630 <!-- node-name, next, previous, up -->
1632 <p><hr>
1634 Next: <a rel="next" accesskey="n" href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a>,
1638 </div>
1643 ESS allows you to run more than one ESS process simultaneously in the
1644 same session. Each process has a name and a number; the initial process
1645 <a name="index-process-names-20"></a>(process 1) is simply named (using S-PLUS as an example) `<samp><span class="samp">S+3:1</span></samp>'.
1646 <!-- You may start a new process by passing a numeric argument to -->
1647 <!-- @kbd{M-x S}. For example, typing @kbd{ESC 2 M-x S} starts up -->
1648 <!-- an ESS process with name @samp{S2}, in a buffer whose name -->
1649 <!-- is initially @samp{*S2*}. -->
1650 The name of the process is shown in the mode line in square brackets
1651 (for example, `<samp><span class="samp">[S+3:2]</span></samp>'); this is useful if the process buffer is
1653 process, using the first available process number. With a prefix
1655 command line options.
1657 <p><a name="index-ess_002drequest_002da_002dprocess-21"></a>You can switch to any active ESS process with the command
1658 `<samp><span class="samp">M-x ess-request-a-process</span></samp>'. Just enter the name of the process
1659 you require; completion is provided over the names of all running S
1660 processes. This is a good command to consider binding to a global key.
1662 <!-- SJE - commented outl the default behaviour now is to label *S* rather -->
1663 <!-- than *S:1*. -->
1664 <!-- @vindex ess-plain-first-buffername -->
1665 <!-- For the predecessor to ESS (S-mode 4.8), the initial process was not -->
1666 <!-- visibly numbered, i.e. S instead of S1 was used in the mode-line. To -->
1667 <!-- obtain this behavior, set the variable @code{ess-plain-first-buffername} -->
1668 <!-- to @code{t}. See @file{ess-site} for how to set this for all users. -->
1669 <!-- node-name, next, previous, up -->
1671 <p><hr>
1673 Next: <a rel="next" accesskey="n" href="#S_002belsewhere-and-ESS_002delsewhere">S+elsewhere and ESS-elsewhere</a>,
1674 Previous: <a rel="previous" accesskey="p" href="#Multiple-ESS-processes">Multiple ESS processes</a>,
1677 </div>
1681 <p><a name="index-Remote-Computers-22"></a><a name="index-ess_002dremote-23"></a><a name="index-ESS_002delsewhere-24"></a><a name="index-S_002belsewhere-25"></a>
1682 ESS works with processes on remote computers as easily as with
1683 processes on the local machine. The recommended way to access a
1684 statistical program on remote computer is to start it from a telnet or
1685 ssh buffer and then connect ESS to that buffer.
1688 <li>Start a new telnet or ssh buffer and connect to the remote computer
1689 (e.g. use `<samp><span class="samp">M-x telnet</span></samp>' or `<samp><span class="samp">M-x ssh</span></samp>'; ssh.el is available at
1690 <a href="ftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.el">ftp://ftp.splode.com/pub/users/friedman/emacs-lisp/ssh.el</a>).
1692 <li>Start the ESS process on the remote machine, for example with one of
1693 the commands `<samp><span class="samp">Splus</span></samp>', or `<samp><span class="samp">R</span></samp>', or `<samp><span class="samp">sas -stdio</span></samp>'.
1695 <li>Enter the ESS command `<samp><span class="samp">M-x ess-remote</span></samp>'. You will be prompted for
1696 a program name. Enter `<samp><span class="samp">sp6</span></samp>' or `<samp><span class="samp">r</span></samp>' or `<samp><span class="samp">sas</span></samp>' or another
1697 valid name. Your telnet process is now known to ESS. All the usual
1698 ESS commands (`<samp><span class="samp">C-c C-n</span></samp>' and its relatives) now work with the S
1699 language processes. For SAS you need to use a different command
1700 `<samp><span class="samp">C-c i</span></samp>' (that is a regular `<samp><span class="samp">i</span></samp>', not a `<samp><span class="samp">C-i</span></samp>') to send
1703 <!-- and lets SAS display them formatted correctly as in a SAS log file. -->
1704 With ess-remote you get teletype behavior—the data input, the
1705 log, and the listing all appear in the same buffer. To make this work,
1706 you need to end every PROC and DATA step with a "RUN;" statement. The
1707 "RUN;" statement is what tells SAS that it should process the preceding
1708 input statements.
1710 <li>Graphics (interactive) on the remote machine. If you run X11
1712 on both the local and remote machines then you should be able to
1713 display the graphs locally by setting the `<samp><span class="samp">DISPLAY</span></samp>' environment
1714 variable appropriately. Windows users can download `<samp><span class="samp">xfree86</span></samp>'
1715 from cygwin.
1717 <li>Graphics (static) on the remote machine.
1718 If you don't run the X window system on the local machine, then you can write
1719 graphics to a file on the remote machine, and display the file in
1720 a graphics viewer on the local machine. Most statistical software can
1721 write one or more of postscript, GIF, or JPEG files.
1722 Depending on the versions of emacs and the operating system that you
1723 are running, emacs itself may display `<samp><span class="samp">.gif</span></samp>' and `<samp><span class="samp">.jpg</span></samp>'
1724 files. Otherwise, a graphics file viewer will be needed.
1725 Ghostscript/ghostview may be downloaded to display `<samp><span class="samp">.ps</span></samp>' and
1726 `<samp><span class="samp">.eps</span></samp>' files. Viewers for GIF and JPEG are usually included with
1727 operating systems. See <a href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">ESS(SAS)–Function keys for batch processing</a>,
1728 for more information on using the F12 key for displaying graphics files
1729 with SAS.
1730 </ol>
1732 <p>Should you or a colleague inadvertently start a statistical process in
1733 an ordinary `<samp><span class="samp">*shell*</span></samp>' buffer, the `<samp><span class="samp">ess-remote</span></samp>' command can
1734 be used to convert it to an ESS buffer and allow you to use the ESS
1735 commands with it.
1737 <p>We have two older commands, now deprecated, for accessing ESS processes
1738 on remote computers.
1741 <!-- node-name, next, previous, up -->
1743 <p><hr>
1747 Previous: <a rel="previous" accesskey="p" href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a>,
1750 </div>
1754 <p>These commands are now deprecated. We recommend `<samp><span class="samp">ess-remote</span></samp>'. We
1755 have two versions of the elsewhere function. `<samp><span class="samp">S+elsewhere</span></samp>' is
1756 specific for the S-Plus program. The more general function
1761 You will be prompted for a starting directory. I usually give it my
1762 project directory on the local machine, say `<samp><span class="samp">~myname/myproject/</span></samp>'
1764 <p>Or enter `<samp><span class="samp">M-x ESS-elsewhere</span></samp>'. You will be prompted for an ESS
1765 program and for a starting directory. I usually give it my project
1766 directory on the local machine, say `<samp><span class="samp">~myname/myproject/</span></samp>'
1768 <li>The `<samp><span class="samp">*S+3*</span></samp>' buffer will appear with a prompt from the
1769 local operating system (the unix prompt on a unix workstation or with
1770 cygwin bash on a PC, or the msdos prompt on a PC without bash). emacs
1771 may freeze because the cursor is at the wrong place. Unfreeze it with
1772 `<samp><span class="samp">C-g</span></samp>' then move the cursor to the end with `<samp><span class="samp">M-></span></samp>'.
1773 With `<samp><span class="samp">S+elsewhere</span></samp>' the buffer name is based on the name of the ESS program.
1774 <li>Enter
1775 `<samp><span class="samp">telnet myname@other.machine</span></samp>' (or `<samp><span class="samp">ssh myname@other.machine</span></samp>').
1776 You will be prompted for your password on the remote machine.
1777 Use
1779 before typing the password itself.
1781 <li>Before starting the ESS process, type `<samp><span class="samp">stty -echo nl</span></samp>'
1783 `<samp><span class="samp">nl</span></samp>' turns off the newline that you see as `<samp><span class="samp">^M</span></samp>'.
1785 <li>You are now talking to the unix prompt on the other machine in the
1786 `<samp><span class="samp">*S+3*</span></samp>' buffer. cd into the directory for the current project and start
1787 the ESS process by entering
1788 `<samp><span class="samp">Splus</span></samp>' or `<samp><span class="samp">R</span></samp>' or `<samp><span class="samp">sas -stdio</span></samp>'
1789 as appropriate. If you can login remotely to your Windows 2000, then
1790 you should be able to run `<samp><span class="samp">Sqpe</span></samp>' on the Windows machine. I haven't
1791 tested this and noone has reported their tests to me. You will not be
1792 able to run the GUI through this text-only connection.
1794 <li>Once you get the S or R or SAS prompt, then you are completely connected.
1795 All the `<samp><span class="samp">C-c C-n</span></samp>' and related commands work correctly in sending
1796 commands from `<samp><span class="samp">myfile.s</span></samp>' or `<samp><span class="samp">myfile.r</span></samp>' on the PC to the
1797 `<samp><span class="samp">*S+3*</span></samp>' buffer running the S or R or SAS program on the remote machine.
1799 <li>Graphics on the remote machine works fine. If you run the X window
1800 system on the remote unix machine you should be able to display them in
1801 `<samp><span class="samp">xfree86</span></samp>' on your PC. If you don't run X11, then you can write
1802 graphics to the postscript device and copy it to your PC with dired and
1803 display it with ghostscript.
1804 </ol>
1806 <!-- node-name, next, previous, up -->
1808 <p><hr>
1810 Previous: <a rel="previous" accesskey="p" href="#S_002belsewhere-and-ESS_002delsewhere">S+elsewhere and ESS-elsewhere</a>,
1813 </div>
1817 <p>If you do not wish ESS to prompt for a starting directory when starting
1819 <a name="index-ess_002dask_002dfor_002dess_002ddirectory-26"></a><code>nil</code>. In this case, the starting directory will be set using
1820 one of the following methods:
1825 function, the value returned by this function is used. The default for
1826 this variable is nil.
1829 directory (ending in a slash), this value is used. The default for this
1830 variable is nil.
1832 <li>Otherwise, the working directory of the current buffer is used.
1834 </ol>
1837 does by default) then the value determined by the above rules provides
1838 the default when prompting for the starting directory. Incidentally,
1842 <p>If you like to keep a record of your S sessions, set the variable
1844 filename for the transcript before the ESS process starts.
1847 — User Option: <b>ess-ask-about-transfile</b><var><a name="index-ess_002dask_002dabout_002dtransfile-27"></a></var><br>
1849 transcript.
1850 </p></blockquote></div>
1852 <p><a name="index-transcript-file-28"></a>Enter the name of a file in which to save the transcript at the prompt.
1853 If the file doesn't exist it will be created (and you should give it a
1854 file name ending in `<samp><span class="samp">.St</span></samp>'); if the file already exists the
1855 transcript will be appended to the file. (Note: if you don't set this
1856 variable but you still want to save the transcript, you can still do it
1859 <p>Once these questions are answered (if they are asked at all) the S
1860 process itself is started by calling the program name specified in the
1862 <a name="index-inferior_002dess_002dprogram-29"></a>If you need to pass any arguments to this program, they may be specified
1866 <a name="index-arguments-to-S-program-30"></a>It is not normally necessary to pass arguments to the S program; in
1867 particular do not pass the `<samp><span class="samp">-e</span></samp>' option to <code>Splus</code>, since ESS
1868 provides its own command history mechanism.
1870 <p>By default, the new process will be displayed in the same window in the
1871 current frame. If you wish your S process to appear in a separate
1874 process to appear within another window of the current frame.
1876 <!-- node-name, next, previous, up -->
1878 <p><hr>
1884 </div>
1888 <p><a name="index-entering-commands-31"></a><a name="index-commands-32"></a><a name="index-sending-input-33"></a>
1889 The primary function of the ESS package is to provide an easy-to-use
1890 front end to the S interpreter. This is achieved by running the S
1891 process from within an Emacs buffer, so that the Emacs editing commands
1892 are available to correct mistakes in commands, etc. The features of
1893 Inferior S mode are similar to those provided by the standard Emacs
1894 shell mode (see <a href="emacs.html#Shell-Mode">Shell Mode</a>). Command-line completion of S objects and a number of `hot
1895 keys' for commonly-used S commands are also provided for ease of
1896 typing.
1899 <li><a accesskey="1" href="#Command_002dline-editing">Command-line editing</a>: Entering commands and fixing mistakes
1901 <li><a accesskey="3" href="#Completion-details">Completion details</a>: Advanced completion concepts
1904 <li><a accesskey="6" href="#History-expansion">History expansion</a>: References to historical commands
1906 <li><a accesskey="8" href="#Statistical-Process-running-in-ESS_003f">Statistical Process running in ESS?</a>
1909 </ul>
1911 <!-- node-name, next, previous, up -->
1913 <p><hr>
1917 Previous: <a rel="previous" accesskey="p" href="#Entering-commands">Entering commands</a>,
1920 </div>
1925 Sending a command to the ESS process is as simple as typing it in
1928 <ul>
1930 <a name="index-inferior_002dess_002dsend_002dinput-35"></a>Send the command on the current line to the ESS process.
1931 </ul>
1934 editing commands are available to correct it (see <a href="emacs.html#Basic">Basic</a>). Once the
1936 cursor is not at the end of the line) to send the corrected command to
1937 the ESS process.
1939 <p>ESS provides some other commands which are useful for fixing mistakes:
1941 <ul>
1943 <a name="index-backward_002dkill_002dword-36"></a>Deletes the previous word (such as an object name) on the command line.
1946 <a name="index-comint_002dkill_002dinput-37"></a>Deletes everything from the prompt to point. Use this to abandon a
1947 command you have not yet sent to the ESS process.
1950 <a name="index-comint_002dbol-38"></a>Move to the beginning of the line, and then skip forwards past the
1951 prompt, if any.
1952 </ul>
1955 commands relevant to entering input.
1957 <!-- node-name, next, previous, up -->
1959 <p><hr>
1962 Previous: <a rel="previous" accesskey="p" href="#Command_002dline-editing">Command-line editing</a>,
1965 </div>
1969 <p><a name="index-completion-of-object-names-39"></a><a name="index-command_002dline-completion-40"></a>
1971 that provided by Shell Mode for filenames. In Inferior S mode,
1976 <ul>
1978 <a name="index-comint_002ddynamic_002dcomplete-41"></a>Complete the S object name or filename before point.
1979 </ul>
1981 <p>When the cursor is just after a partially-completed object name,
1985 instead of file names. ESS maintains a list of all objects known to S
1986 at any given time, which basically consists of all objects (functions
1988 command
1989 <a name="index-search_0028_0029-43"></a>along with the component objects of attached data frames
1992 <p>For example, consider the three functions (available in Splus version
1995 insert the characters `<samp><span class="samp">om</span></samp>', completing the longest prefix
1996 (`<samp><span class="samp">binom</span></samp>') which distinguishes these three commands. Pressing
1998 this prefix, allowing you to add more characters (say, `<samp><span class="samp">.</span></samp>') which
1999 specify the function you desire. After entering more characters
2001 uniqueness, etc. If you just wish to see what completions exist without
2004 <ul>
2006 <a name="index-ess_002dlist_002dobject_002dcompletions-45"></a>List all possible completions of the object name at point.
2007 </ul>
2009 <p>ESS also provides completion over the components of named lists accessed
2010 using the `<samp><span class="samp">$</span></samp>' notation, to any level of nested lists. This feature
2011 is particularly useful for checking what components of a list object
2012 exist while partway through entering a command: simply type the object
2013 name and `<samp><span class="samp">$</span></samp>' and press <kbd>TAB</kbd> to see the names of existing list
2014 components for that object.
2016 <a name="index-completion-on-file-names-48"></a>Completion is also provided over file names, which is particularly
2018 which require fully expanded file names. Whenever the cursor is within
2020 point, and also expands any `<samp><span class="samp">~</span></samp>' or environment variable references.
2022 <p>If the cursor is not in a string and does not follow a (partial) object
2026 <!-- node-name, next, previous, up -->
2028 <p><hr>
2034 </div>
2038 <p>ESS automatically keeps track of any objects added or deleted to the
2039 system (such as new objects created, or directories added to the search
2040 list) to make completion as accurate as possible. Whenever ESS notices
2041 that search list has changed
2042 <a name="index-ess_002dchange_002dsp_002dregexp-49"></a><a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a> when you attach a directory or data
2043 frame, the objects associated with it immediately become available for a
2044 completion; when it is detached completion is no longer available on
2045 those objects.
2047 <p>To maintain a list of accessible objects for completion, ESS needs to
2048 determine which objects are contained in each directory or data frame on
2049 the search list. This is done at the start of each S session, by
2051 list.
2053 <!-- On some systems, however, this can be rather slow; it's doubly -->
2054 <!-- frustrating when you consider that most of the directories on the search -->
2055 <!-- list are the standard @Sl{} libraries, which never change anyway! When -->
2056 <!-- ESS was installed, a database of the standard object names should have -->
2057 <!-- been created which should speed up this process at the start of an S -->
2058 <!-- session; if it has not been created you will get a warning like -->
2059 <!-- `S-namedb.el does not exist'. @xref{Installation}, for information on -->
2060 <!-- how to create this database. -->
2061 <p>Efficiency in completion is gained by maintaining a cache of objects
2062 currently known to S; when a new object becomes available or is deleted,
2063 only one component of the cache corresponding to the associated
2064 directory needs to be refreshed. If ESS ever becomes confused about
2065 what objects are available for completion (such as when if refuses to
2067 ess-resynch</kbd>
2068 <a name="index-ess_002dresynch-50"></a>forces the <em>entire</em> cache to be refreshed, which should fix the
2069 problem.
2071 <!-- node-name, next, previous, up -->
2073 <p><hr>
2076 Previous: <a rel="previous" accesskey="p" href="#Completion-details">Completion details</a>,
2079 </div>
2083 <p>Most of the time, the cursor spends most of its time at the bottom of
2084 the ESS process buffer, entering commands. However all the input
2085 and output from the current (and previous) ESS sessions is stored in
2086 the process buffer (we call this the transcript) and often we want to
2087 <a name="index-transcript-51"></a>move back up through the buffer, to look at the output from previous
2088 commands for example.
2090 <p>Within the process buffer, a paragraph
2091 <a name="index-paragraphs-in-the-process-buffer-52"></a>is defined as the prompt, the command after the prompt, and the output
2093 forwards, respectively, through commands in the transcript. A
2095 will allow you to mark a command and its entire output (for deletion,
2096 perhaps). For more information about paragraph commands,
2099 <p>If an ESS process finishes and you restart it in the same process
2100 buffer, the output from the new ESS process appears after the output
2101 from the first ESS process separated by a form-feed (`<samp><span class="samp">^L</span></samp>')
2102 character. Thus pages in the ESS
2103 <a name="index-pages-in-the-process-buffer-53"></a>process buffer correspond to ESS sessions. Thus, for example, you may
2105 ESS sessions in a single ESS process buffer. For more information about
2109 <li><a accesskey="1" href="#Last-command">Last command</a>: Manipulating the output from the last command
2110 <li><a accesskey="2" href="#Process-buffer-motion">Process buffer motion</a>: Viewing older commands
2111 <li><a accesskey="3" href="#Transcript-resubmit">Transcript resubmit</a>: Re-submitting commands from the transcript
2112 <li><a accesskey="4" href="#Saving-transcripts">Saving transcripts</a>: Keeping a record of your S session
2113 </ul>
2115 <!-- node-name, next, previous, up -->
2117 <p><hr>
2119 Next: <a rel="next" accesskey="n" href="#Process-buffer-motion">Process buffer motion</a>,
2123 </div>
2127 <p>Viewing the output of the command you have just entered is a common
2128 occurrence and ESS provides a number of facilities for doing this.
2129 <!-- Within the ESS process buffer, the variable @code{scroll-step} -->
2130 <!-- @vindex scroll-step -->
2131 <!-- is set to 4 (you can redefine this using @code{inferior-ess-mode-hook} -->
2132 <!-- @vindex inferior-ess-hook -->
2133 <!-- if you wish - @pxref{Hooks},) so that the cursor is usually near the -->
2134 <!-- bottom of the window. -->
2135 Whenever a command produces a longish output, it is possible that the
2136 window will scroll, leaving the next prompt near the middle of the
2137 window. The first part of the command output may have scrolled off the
2138 top of the window, even though the entire output would fit in the window
2139 if the prompt were near the bottom of the window. If this happens, you
2140 can use the command
2142 <ul>
2144 <a name="index-comint_002dshow_002dmaximum_002doutput-54"></a>Move to the end of the buffer, and place cursor on bottom line of
2145 window.
2146 </ul>
2149 automatically for all inputs, set the variable
2152 <p>If the first part of the output is still obscured, use
2154 <ul>
2156 <a name="index-comint_002dshow_002doutput-56"></a>Moves cursor to the previous command line and and places it at the top
2157 of the window.
2158 </ul>
2161 altogether, use
2163 <ul>
2165 <a name="index-comint_002dkill_002doutput-57"></a><a name="index-deleting-output-58"></a>Deletes everything from the last command to the current prompt.
2166 </ul>
2169 more manageable size.
2171 <!-- node-name, next, previous, up -->
2173 <p><hr>
2179 </div>
2183 <p>If you want to view the output from more historic commands than the
2184 previous command, commands are also provided to move backwards and
2185 forwards through previously entered commands in the process buffer:
2187 <ul>
2189 <a name="index-comint_002dprevious_002dinput-59"></a>Moves point to the preceding command in the process buffer.
2192 <a name="index-comint_002dnext_002dinput-60"></a>Moves point to the next command in the process buffer.
2193 </ul>
2195 <p class="noindent">Note that these two commands are analogous to <kbd>C-p</kbd> and <kbd>C-n</kbd>
2196 but apply to command lines rather than text lines. And just like
2199 commands are also discussed in <a href="emacs.html#Shell-History-Copying">Shell History Copying</a>.)
2201 <p>There are also two similar commands (not bound to any keys by default)
2202 which move to preceding or succeeding commands, but which first prompt
2203 for a regular expression (see <a href="emacs.html#Regexps">Syntax of Regular Expression</a>), and then moves to
2204 the next (previous) command matching the pattern.
2206 <ul>
2208 <a name="index-comint_002dbackward_002dmatching_002dinput-61"></a><code>(comint-forward-matching-input regexp arg)</code> <br>
2209 <a name="index-comint_002dforward_002dmatching_002dinput-62"></a>Search backward (forward) through the transcript buffer for the
2212 </ul>
2214 <!-- node-name, next, previous, up -->
2216 <p><hr>
2219 Previous: <a rel="previous" accesskey="p" href="#Process-buffer-motion">Process buffer motion</a>,
2222 </div>
2226 <p>When moving through the transcript, you may wish to re-execute some of
2227 the commands you find there. ESS provides three commands to do this;
2228 these commands may be used whenever the cursor is within a command line
2231 key.
2233 <ul>
2235 <a name="index-inferior_002dess_002dsend_002dinput-63"></a>Copy the command under the cursor to the current command line, and
2236 execute it.
2239 <a name="index-comint_002dcopy_002dold_002dinput-64"></a>Copy the command under the cursor to the current command line, but don't
2240 execute it. Leaves the cursor on the command line so that the copied
2241 command may be edited.
2244 <a name="index-ess_002dtranscript_002dsend_002dcommand_002dand_002dmove-65"></a>Copy the command under the cursor to the current command line, and
2245 execute it. Moves the cursor to the following command.
2246 </ul>
2250 line containing a command that you entered (i.e. a line beginning with a
2251 prompt) sends that command to the ESS process once again. If you
2253 it copies the command to the current prompt but does not execute it,
2254 allowing you to edit it before submitting it.
2256 <p>These two commands leave the cursor at the new command line, allowing
2257 you to continue with interactive use of S. If you wish to resubmit a
2259 instead, which leaves the cursor at the command line following the one
2261 re-submit a whole series of commands.
2263 <p>These commands work even if if the current line is a continuation line
2264 (i.e. the prompt is `<samp><span class="samp">+</span></samp>' instead of `<samp><span class="samp">></span></samp>') — in this case all
2265 the lines that form the multi-line command are concatenated together and
2266 the resulting command is sent to the ESS process (currently this is
2267 the only way to resubmit a multi-line command to the ESS process in
2268 one go). If the current line does
2269 <a name="index-multi_002dline-commands_002c-resubmitting-66"></a>not begin with a prompt, an error is signalled. This feature, coupled
2270 with the command-based motion commands described above, could be used as
2271 a primitive history mechanism. ESS provides a more sophisticated
2274 <!-- node-name, next, previous, up -->
2276 <p><hr>
2278 Previous: <a rel="previous" accesskey="p" href="#Transcript-resubmit">Transcript resubmit</a>,
2281 </div>
2285 <p>To keep a record of your S session in a disk file, use the Emacs
2287 ESS process buffer. The name of the process buffer will (probably)
2288 change to the name of the file, but this is not a problem. You can
2289 still use S as usual; just remember to save the file before you quit
2291 which to save the transcript every time you start S by setting the
2292 variable
2293 <a name="index-ess_002dask_002dabout_002dtransfile-67"></a><code>ess-ask-about-transfile</code> to <code>t</code>; see <a href="#Customizing-startup">Customizing startup</a>.
2294 <a name="index-transcript-file-names-68"></a>We recommend you save your transcripts with filenames that end in
2295 `<samp><span class="samp">.St</span></samp>'. There is a special mode (ESS transcript mode —
2297 automatically selected for files with this suffix.
2299 <p><a name="index-editing-transcripts-69"></a>S transcripts can get very large, so some judicious editing is
2301 a command produces excessively long output (printing large arrays, for
2302 example). Delete erroneous commands (and the resulting error messages
2303 or other output) by moving to the command (or its output) and typing
2305 may be used for commands whose output you do not wish to appear in the
2306 transcript. These suggestions are appropriate even if you are not
2307 saving your transcript to disk, since the larger the transcript, the
2308 more memory your Emacs process will use on the host machine.
2310 <p>Finally, if you intend to produce S source code (suitable for using
2313 be of use.
2314 <a name="index-ess_002dtranscript_002dclean_002dregion-70"></a>This command works in any Emacs buffer, and removes all prompts and
2315 command output from an ESS transcript within the current region, leaving
2316 only the commands. Don't forget to remove any erroneous commands first!
2318 <!-- node-name, next, previous, up -->
2320 <p><hr>
2326 </div>
2330 <p><a name="index-command-history-71"></a><a name="index-editing-commands-72"></a><a name="index-re_002dexecuting-commands-73"></a>
2331 ESS provides easy-to-use facilities for re-executing or editing previous
2332 commands. An input history of the last few commands is maintained (by
2333 default the last 50 commands are stored, although this can be changed by
2335 <a name="index-comint_002dinput_002dring_002dsize-74"></a><code>inferior-ess-mode-hook</code>.) The simplest history commands simply
2336 select the next and previous commands in the input history:
2338 <ul>
2340 <a name="index-comint_002dprevious_002dinput-75"></a>Select the previous command in the input history.
2344 </ul>
2346 <p class="noindent">For example, pressing <kbd>M-p</kbd> once will re-enter the last command into
2347 the process buffer after the prompt but does not send it to the ESS
2348 process, thus allowing editing or correction of the command before the
2349 ESS process sees it. Once corrections have been made, press
2352 <p>If you want to select a particular command from the history by matching
2353 it against a regular expression (see <a href="emacs.html#Regexps">Syntax of Regular Expression</a>), to search for a
2354 particular variable name for example, these commands are also available:
2356 <ul>
2358 <a name="index-comint_002dprevious_002dmatching_002dinput-77"></a>Prompt for a regular expression, and search backwards through the input
2359 history for a command matching the expression.
2362 <a name="index-comint_002dnext_002dmatching_002dinput-78"></a>Prompt for a regular expression, and search backwards through the input
2363 history for a command matching the expression.
2364 </ul>
2367 particular sequence of characters; the following two commands provide an
2368 easy way to do this:
2370 <ul>
2372 <a name="index-comint_002dprevious_002dmatching_002dinput_002dfrom_002dinput-79"></a>Select the previous command in the history which matches the string
2373 typed so far.
2376 <a name="index-comint_002dnext_002dmatching_002dinput_002dfrom_002dinput-80"></a>Select the next command in the history which matches the string typed so
2377 far.
2378 </ul>
2381 instead select commands starting with those characters already entered.
2385 in which case it may be a good idea to bind these commands to some other
2386 keys.)
2388 <p>See <a href="emacs.html#Shell-Ring">Shell History Ring</a>, for a more detailed discussion of the history mechanism.
2390 <!-- node-name, next, previous, up -->
2392 <p><hr>
2398 </div>
2402 <p>Instead of searching through the command history using the command
2403 described in the previous section, you can alternatively refer to a
2404 historical command directly using a notation very similar to that used
2405 in <code>csh</code>. History references are introduced by a `<samp><span class="samp">!</span></samp>' or
2408 <dl>
2411 <br><dt>`<samp><span class="samp">!-</span><var>N</var></samp>'<dd>The <var>N</var>th previous command
2413 <br><dt>`<samp><span class="samp">!text</span></samp>'<dd>The last command beginning with the string `<samp><span class="samp">text</span></samp>'
2415 <br><dt>`<samp><span class="samp">!?text</span></samp>'<dd>The last command containing the string `<samp><span class="samp">text</span></samp>'
2416 </dl>
2420 sequence of characters separated by whitespace. (You can modify this
2422 to a list of characters that are allowed to separate words and
2423 <a name="index-comint_002ddelimiter_002dargument_002dlist-81"></a>themselves form words.) Words are numbered beginning with zero. The
2424 word designator usually begins with a `<samp><span class="samp">:</span></samp>' (colon) character;
2425 however it may be omitted if the word reference begins with a `<samp><span class="samp">^</span></samp>',
2426 `<samp><span class="samp">$</span></samp>', `<samp><span class="samp">*</span></samp>' or `<samp><span class="samp">-</span></samp>'. If the word is to be selected from the
2427 previous command, the second `<samp><span class="samp">!</span></samp>' character can be omitted from the
2428 event specification. For instance, `<samp><span class="samp">!!:1</span></samp>' and `<samp><span class="samp">!:1</span></samp>' both
2429 refer to the first word of the previous command, while `<samp><span class="samp">!!$</span></samp>' and
2430 `<samp><span class="samp">!$</span></samp>' both refer to the last word in the previous command. The
2431 format of word designators is as follows:
2433 <dl>
2434 <dt>`<samp><span class="samp">0</span></samp>'<dd>The zeroth word (i.e. the first one on the command line)
2438 <br><dt>`<samp><span class="samp">^</span></samp>'<dd>The first word (i.e. the second one on the command line)
2442 <br><dt>`<samp><var>x</var><span class="samp">-</span><var>y</var></samp>'<dd>A range of words; `<samp><span class="samp">-</span><var>y</var></samp>' abbreviates `<samp><span class="samp">0-</span><var>y</var></samp>'
2444 <br><dt>`<samp><span class="samp">*</span></samp>'<dd>All the words except the zeroth word, or nothing if the command had just
2445 one word (the zeroth)
2449 <br><dt>`<samp><var>x</var><span class="samp">-</span></samp>'<dd>Like `<samp><var>x</var><span class="samp">*</span></samp>', but omitting the last word
2450 </dl>
2452 <p>In addition, you may surround the entire reference except for the first
2453 `<samp><span class="samp">!</span></samp>' by braces to allow it to be followed by other (non-whitespace)
2454 characters (which will be appended to the expanded reference).
2456 <p>Finally, ESS also provides quick substitution; a reference like
2457 `<samp><span class="samp">^old^new^</span></samp>' means “the last command, but with the first occurrence
2458 of the string `<samp><span class="samp">old</span></samp>' replaced with the string `<samp><span class="samp">new</span></samp>'” (the last
2459 `<samp><span class="samp">^</span></samp>' is optional). Similarly, `<samp><span class="samp">^old^</span></samp>' means “the last
2460 command, with the first occurrence of the string `<samp><span class="samp">old</span></samp>' deleted”
2463 <p>To convert a history reference as described above to an input suitable
2466 (otherwise it would try to complete an object name) and not be within a
2467 string (otherwise it would try to complete a filename). So to expand
2469 history reference into an S command from the history, which you can
2472 <p>For example, to execute the last command that referenced the variable
2475 <!-- node-name, next, previous, up -->
2477 <p><hr>
2479 Next: <a rel="next" accesskey="n" href="#Statistical-Process-running-in-ESS_003f">Statistical Process running in ESS?</a>,
2480 Previous: <a rel="previous" accesskey="p" href="#History-expansion">History expansion</a>,
2483 </div>
2487 <p>ESS provides a number of commands for executing the commonly used
2488 functions. These commands below are basically information-gaining
2490 clutter up your transcript and for this reason some of the hot keys
2491 display their output in a temporary buffer instead of the process buffer
2492 by default. This behavior is controlled by the variable
2494 <a name="index-ess_002dexecute_002din_002dprocess_002dbuffer-82"></a>non-<code>nil</code>, means that these commands will produce their output in
2495 the process buffer instead. In any case, passing a prefix argument to
2498 will be displayed in the process buffer if it usually goes to a
2499 temporary buffer, and vice-versa. These are the hot keys that behave in
2500 this way:
2502 <ul>
2505 <a name="index-objects_0028_0029-84"></a>command to the ESS process. A prefix argument specifies the
2506 position on the search list (use a negative argument to toggle
2508 objects are in your working directory.
2516 </ul>
2519 command in anyway, but it proves useful for `spot' calculations which
2520 would otherwise clutter your transcript, or for evaluating an expression
2521 while partway through entering a command. You can also use this command
2522 to generate new hot keys using the Emacs keyboard macro facilities;
2526 to decide where to display the output — they either always display in
2527 the process buffer or in a separate buffer, as indicated:
2529 <ul>
2531 <a name="index-ess_002dexecute_002dattach-94"></a>Prompts for a directory to attach to the ESS process with the
2533 <a name="index-attach_0028_0029-95"></a>If a numeric prefix argument is given it is used as the position on the
2534 search list to attach the directory; otherwise the S default of 2 is
2536 process buffer.
2539 <a name="index-ess_002dload_002dfile-96"></a>Prompts for a file to load into the ESS process using
2542 <a name="index-ess_002dparse_002derrors-97"></a>See <a href="#Error-Checking">Error Checking</a>, for more details.
2546 details.
2549 <a name="index-quitting-from-ESS-98"></a><a name="index-killing-the-ESS-process-99"></a>Sends the <code>q()</code>
2551 <a name="index-exit_0028_0029-101"></a>to the <b>XLS</b> process), and cleans up any temporary buffers (such as
2552 help buffers or edit buffers) you may have created along the way. Use
2553 this command when you have finished your S session instead of simply
2556 <a name="index-ess_002dcleanup-102"></a><a name="index-cleaning-up-103"></a><a name="index-temporary-buffers_002c-killing-104"></a><a name="index-killing-temporary-buffers-105"></a>command explicitly to make sure that all the files that need to be saved
2557 have been saved, and that all the temporary buffers have been killed.
2558 </ul>
2560 <!-- node-name, next, previous, up -->
2562 <p><hr>
2569 </div>
2573 <p><a name="index-STERM-106"></a><a name="index-STERM-107"></a>For the S languages (S, S-Plus, R) ESS sets an option in the current
2574 process that programs in the language can check to determine the
2575 environment in which they are currently running.
2577 <p>ESS sets
2579 inferior <code>i<acronym>ESS[S]</acronym><!-- /@w --></code> or <code>i<acronym>ESS[R]</acronym><!-- /@w --></code> buffer.
2581 <p>ESS sets
2583 processes running in the GUI and communicating with ESS via
2584 the DDE (Microsoft Dynamic Data Exchange) protocol through a
2589 <ul>
2596 </ul>
2598 <p>Additional values may be recommended in the future as new interaction
2600 ESS can't set these other values since the S language program is not
2601 under the control of ESS.
2603 <!-- node-name, next, previous, up -->
2605 <p><hr>
2608 Previous: <a rel="previous" accesskey="p" href="#Statistical-Process-running-in-ESS_003f">Statistical Process running in ESS?</a>,
2611 </div>
2616 When starting R or S under Unix, ESS sets
2618 use gnuclient.exe rather than emacsclient, but the same principle
2619 applies.) Within your R session, for example, if you have a function
2621 function in a temporary Emacs buffer. You can then correct the
2622 function. When you kill the buffer, the definition of the function is
2626 Emacs buffer.
2628 <!-- node-name, next, previous, up -->
2630 <p><hr>
2635 </div>
2639 <p>The following commands are also provided in the process buffer:
2641 <ul>
2643 <a name="index-comint_002dinterrupt_002dsubjob-109"></a>Sends a Control-C signal to the ESS process. This has the effect of
2644 <a name="index-aborting-S-commands-110"></a><a name="index-interrupting-S-commands-111"></a>aborting the current command.
2647 <a name="index-ess_002dabort-112"></a><a name="index-comint_002dstop_002dsubjob-113"></a>Sends a STOP signal to the ESS process, killing it immediately.
2650 cleanly. This command is provided as a safety to
2655 <a name="index-ess_002ddump_002dobject_002dinto_002dedit_002dbuffer-116"></a>Prompts for an object to be edited in an edit buffer. See <a href="#Editing">Editing</a>.
2656 </ul>
2658 <p>Other commands available in Inferior S mode are discussed in
2661 <!-- node-name, next, previous, up -->
2663 <p><hr>
2666 Previous: <a rel="previous" accesskey="p" href="#Entering-commands">Entering commands</a>,
2669 </div>
2673 <p>Inferior S mode records the transcript (the list of all commands
2674 executed, and their output) in the process buffer, which can be saved as
2676 <samp><span class="file">.St</span></samp>. The most obvious use for a transcript file is as a static
2677 record of the actions you have performed in a particular S session.
2678 Sometimes, however, you may wish to re-execute commands recorded in the
2679 transcript file by submitting them to a running ESS process. This
2680 is what Transcript Mode is for.
2682 <p>If you load file a with the suffix <samp><span class="file">.St</span></samp> into Emacs, it is placed
2683 in S Transcript Mode. Transcript Mode is similar to Inferior S mode
2685 <a name="index-transcript-mode-motion-117"></a><a name="index-motion-in-transcript-mode-118"></a>paragraphs are defined as a command and its output, and you can move
2690 <li><a accesskey="1" href="#Resubmit">Resubmit</a>: Resubmitting commands from the transcript file
2692 </ul>
2694 <!-- node-name, next, previous, up -->
2696 <p><hr>
2702 </div>
2706 <p>Three commands are provided to re-submit command lines from the
2707 transcript file to a running ESS process. They are:
2709 <ul>
2711 Send the current command line to the ESS process, and execute it.
2714 Copy the current command to the ESS process, and switch to the
2715 ESS process buffer (ready to edit the copied command).
2718 Send the current command to the ESS process, and move to the next
2719 command line. This command is useful for submitting a series of
2720 commands.
2721 </ul>
2724 Inferior S Mode. In all three cases, the commands should be
2725 executed when the cursor is on a command line in the transcript; the
2726 prompt is automatically removed before the command is submitted.
2728 <!-- node-name, next, previous, up -->
2730 <p><hr>
2735 </div>
2739 <p>Yet another use for transcript files is to extract the command lines for
2740 inclusion in an S source file or function. Transcript mode provides
2741 one command which does just this:
2743 <ul>
2745 Deletes all prompts and command output in the region, leaving only the
2746 commands themselves.
2747 </ul>
2750 buffer for inclusion in a function definition, or may be evaluated
2751 directly (see <a href="#Evaluating-code">Evaluating code</a>) using the code evaluation commands
2752 from S mode, also available in S Transcript Mode.
2754 <!-- node-name, next, previous, up -->
2756 <p><hr>
2762 </div>
2768 <li><a accesskey="2" href="#iESS_0028S_0029_002d_002dInferior-ESS-processes">iESS(S)--Inferior ESS processes</a>
2769 <li><a accesskey="3" href="#ESS_002dhelp_002d_002dassistance-with-viewing-help">ESS-help--assistance with viewing help</a>
2770 <li><a accesskey="4" href="#Philosophies-for-using-ESS_0028S_0029">Philosophies for using ESS(S)</a>
2771 <li><a accesskey="5" href="#Scenarios-for-use-_0028possibilities_002d_002dbased-on-actual-usage_0029">Scenarios for use (possibilities--based on actual usage)</a>
2772 <li><a accesskey="6" href="#Customization-Examples-and-Solutions-to-Problems">Customization Examples and Solutions to Problems</a>
2773 </ul>
2776 <p><hr>
2779 Next: <a rel="next" accesskey="n" href="#iESS_0028S_0029_002d_002dInferior-ESS-processes">iESS(S)--Inferior ESS processes</a>,
2782 </div>
2784 <!-- node-name, next, previous, up - don't use @ESS .. -->
2789 <ul>
2790 <li> proper indenting, generated by both [Tab] and [Return].
2791 <li> color and font choices based on syntax.
2792 <li> ability to send the contents of an entire buffer, a highlighted
2793 region, an S function, or a single line to an inferior S process, if
2794 one is currently running.
2795 <li> ability to switch between processes which would be the target of the
2796 buffer (for the above).
2797 <li> The ability to request help from an S process for variables and
2798 functions, and to have the results sent into a separate buffer.
2799 <li> completion of object names and file names.
2800 </ul>
2803 the suffices found in ess-site (*.R, *.S, *.s, etc). However, one
2804 will have to start up an inferior process to take advantage of the
2805 interactive features.
2808 <p><hr>
2811 Next: <a rel="next" accesskey="n" href="#ESS_002dhelp_002d_002dassistance-with-viewing-help">ESS-help--assistance with viewing help</a>,
2812 Previous: <a rel="previous" accesskey="p" href="#ESS_0028S_0029_002d_002dEditing-files">ESS(S)--Editing files</a>,
2815 </div>
2817 <!-- node-name, next, previous, up -->
2820 <p>iESS (inferior ESS) is the mode for interfacing with active
2821 statistical processes (programs). This mode handles:
2823 <ul>
2824 <li> proper indenting, generated by both [Tab] and [Return].
2825 <li> color and font highlighting based on syntax.
2826 <li> ability to resubmit the contents of a multi-line command
2827 to the executing process with a single keystroke [RET].
2828 <li> The ability to request help from the current process for variables
2829 and functions, and to have the results sent into a separate buffer.
2830 <li> completion of object names and file names.
2831 <li> interactive history mechanism.
2832 <li> transcript recording and editing.
2833 </ul>
2835 <p>To start up iESS mode, use:
2837 M-x S4
2838 M-x S+5
2839 M-x S+6
2840 M-x R
2841 </pre>
2843 you have access to each). Usually the site will have defined one of
2844 these programs (by default S+6) to the simpler name:
2846 <p>M-x S
2848 <p>In the (rare) case that you wish to pass command line arguments to the
2851 <p>Note that R has some extremely useful command line arguments. For
2853 files. To enter a command line argument, call R using a "prefix
2854 argument", by
2856 <p>C-u M-x R
2863 wish to always call R with certain arguments, set the variable
2866 <!-- Menubar access to other versions of R and Sqpe -->
2867 <p>If you have other versions of R or S-Plus available on the system, ESS
2868 is also able to start those versions. How this works depend on which OS
2869 you are using:
2871 <p>R on Unix systems:
2872 If you have "R-1.8.1" on
2875 versions of R are called other names, consider renaming them with a
2877 which defuns have been created for starting different versions of R,
2879 for particular versions of R have been created. These other versions of
2880 R can also be started from the "ESS->Start Process->Other" menu.
2882 <p>R on Windows systems:
2883 If you have "rw1081" on
2885 default, ESS will find versions of R located in directories
2887 versions of R are called other names, you will need to change the variable
2889 which defuns have been created for starting different versions of R,
2891 for particular versions of R have been created. These other versions of
2892 R can also be started from the "ESS->Start Process->Other" menu.
2894 <p>Once ESS has found these extra versions of R, it will then create a new
2896 R that it found. (ESS examines the date in the first line of
2901 executables beginning "Splus" on your path. If your versions of S are
2902 called other names, consider renaming them with a symbolic link or
2904 been created for starting different versions of Splus, type <kbd>M-x
2905 Splus</kbd> and then hit [Tab]. You will then see if any defuns for
2906 particular versions of Splus have been created. These other versions of
2907 Splus can also be started from the "ESS->Start Process->Other" menu.
2909 <p>A second mechanim is also available for running other versions of Splus.
2911 should be of the form: (DEFUN-NAME PATH ARGS). DEFUN-NAME is the name
2912 of the new emacs function you wish to create to start the new S process;
2913 PATH is the full path to the version of S you want to run; ARGS is an
2914 optional string of command-line arguments to pass to the S process.
2915 Here is an example setting:
2919 </pre>
2921 with the corresponding command line arguments.
2925 ess-site is loaded, since the new emacs functions are created when ESS
2926 is loaded.
2928 <p>Sqpe (S-Plus running inside an emacs buffer) on Windows systems:
2929 If you have an older version of S-Plus (S-Plus 6.1 for example) on your system,
2931 default, ESS will find versions of S-Plus located in the installation
2932 directories that Insightful uses by default. If your
2933 versions of S-Plus are anywhere else, you will need to change the variable
2935 which defuns have been created for starting different versions of S-Plus,
2937 for particular versions of S-Plus have been created. These other versions of
2938 S-Plus can also be started from the "ESS->Start Process->Other" menu.
2941 <p><hr>
2944 Next: <a rel="next" accesskey="n" href="#Philosophies-for-using-ESS_0028S_0029">Philosophies for using ESS(S)</a>,
2945 Previous: <a rel="previous" accesskey="p" href="#iESS_0028S_0029_002d_002dInferior-ESS-processes">iESS(S)--Inferior ESS processes</a>,
2948 </div>
2950 <!-- node-name, next, previous, up -->
2956 <p><hr>
2959 Next: <a rel="next" accesskey="n" href="#Scenarios-for-use-_0028possibilities_002d_002dbased-on-actual-usage_0029">Scenarios for use (possibilities--based on actual usage)</a>,
2960 Previous: <a rel="previous" accesskey="p" href="#ESS_002dhelp_002d_002dassistance-with-viewing-help">ESS-help--assistance with viewing help</a>,
2963 </div>
2967 <p>The first is preferred, and configured for. The second one can be
2968 retrieved again, by changing emacs variables.
2971 real. The objects are realizations of the source code. Source
2972 for EVERY user modified object is placed in a particular directory
2973 or directories, for later editing and retrieval.
2976 realization of the objects. Dumped buffers should not be saved.
2977 _We_strongly_discourage_this_approach_. However, if you insist,
2978 add the following lines to your .emacs file:
2980 (setq ess-delete-dump-files t)
2981 (setq ess-mode-silently-save nil)
2982 </pre>
2983 <p>The second saves a small amount of disk space. The first allows for
2984 better portability as well as external version control for code.
2987 <p><hr>
2990 Next: <a rel="next" accesskey="n" href="#Customization-Examples-and-Solutions-to-Problems">Customization Examples and Solutions to Problems</a>,
2991 Previous: <a rel="previous" accesskey="p" href="#Philosophies-for-using-ESS_0028S_0029">Philosophies for using ESS(S)</a>,
2994 </div>
2998 <p>We present some basic suggestions for using ESS to interact with S.
2999 These are just a subset of approaches, many better approaches are
3000 possible. Contributions of examples of how you work with ESS are
3001 appreciated (especially since it helps us determine priorities on
3002 future enhancements)! (comments as to what should be happening are
3003 prefixed by "##").
3005 ## Load the file you want to work with
3006 C-x C-f myfile.s
3008 ## Edit as appropriate, and then start up S-PLUS 3.x
3009 M-x S+3
3014 ## Split the screen and go back to the file editing buffer.
3015 C-x 2 C-x b myfile.s
3017 ## Send regions, lines, or the entire file contents to S-PLUS. For regions,
3018 ## highlight a region with keystrokes or mouse and then send with:
3019 C-c C-r
3021 ## Re-edit myfile.s as necessary to correct any difficulties. Add
3022 ## new commands here. Send them to S by region with C-c C-r, or
3023 ## one line at a time with C-c C-n.
3025 ## Save the revised myfile.s with C-x C-s.
3028 ## will be prompted for a file name. The recommended name is
3029 ## myfile.St. With the *.St suffix, the file will come up in ESS
3030 ## Transcript mode the next time it is accessed from Emacs.
3034 2: ## Program revision example (source code is real)
3037 M-x S+3
3039 ## Load the file you want to work with
3040 C-x C-f myfile.s
3042 ## edit program, functions, and code in myfile.s, and send revised
3043 ## functions to S when ready with
3044 C-c C-f
3045 ## or highlighted regions with
3046 C-c C-r
3047 ## or individual lines with
3048 C-c C-n
3049 ## or load the entire buffer with
3050 C-c C-l
3052 ## save the revised myfile.s when you have finished
3053 C-c C-s
3057 3: ## Program revision example (S object is real)
3060 M-x S+3
3062 ## Dump an existing S object my.function into a buffer to work with
3063 C-c C-d my.function
3064 ## a new buffer named yourloginname.my.function.S will be created with
3065 ## an editable copy of the object. The buffer is associated with the
3066 ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not
3067 ## exist after you log off.
3069 ## enter program, functions, and code into work buffer, and send
3070 ## entire contents to S-PLUS when ready
3071 C-c C-b
3074 ## the results.
3075 C-c C-y
3078 ## Return to the work buffer (may/may not be prefixed)
3079 C-x C-b yourloginname.my.function.S
3080 ## Fix the function that didn't work, and resubmit by placing the
3081 ## cursor somewhere in the function and
3082 C-c C-f
3083 ## Or you could've selected a region (using the mouse, or keyboard
3084 ## via setting point/mark) and
3085 C-c C-r
3086 ## Or you could step through, line by line, using
3087 C-c C-n
3088 ## Or just send a single line (without moving to the next) using
3089 C-c C-j
3090 ## To fix that error in syntax for the "rchisq" command, get help
3091 ## by
3092 C-c C-v rchisq
3095 4: Data Analysis (S object is real)
3097 M-x S+3
3099 ## Work in the process buffer. When you find an object that needs
3100 ## to be changed (this could be a data frame, or a variable, or a
3101 ## function), dump it to a buffer:
3102 C-c C-d my.cool.function
3104 ## Edit the function as appropriate, and dump back in to the
3105 ## process buffer
3106 C-c C-b
3108 ## Return to the S-PLUS process buffer
3109 C-c C-y
3110 ## Continue working.
3112 ## When you need help, use
3113 C-c C-v rchisq
3114 ## instead of entering: help("rchisq")
3115 </pre>
3117 <p><hr>
3119 Previous: <a rel="previous" accesskey="p" href="#Scenarios-for-use-_0028possibilities_002d_002dbased-on-actual-usage_0029">Scenarios for use (possibilities--based on actual usage)</a>,
3122 </div>
3128 we've stuck you with. Simply edit the "ess-dialect" alist entry in
3130 "S+3". This will ensure that all the inferior process buffer names
3131 are "*S*".
3135 you heavy simulation people). Then uncomment the line in ess-site
3136 (or add after your (require 'ess-site) or (load "ess-site") command
3137 in your .emacs file, the line:
3139 </pre>
3140 <p>)
3143 Splus dumps, a mis-matched " (double-quote) can result in the
3144 wrong font-lock face being used for the remainder of the buffer.
3147 revert the font-lock face back to normal.
3149 <!-- node-name, next, previous, up -->
3151 <p><hr>
3153 Next: <a rel="next" accesskey="n" href="#Editing-R-documentation-files">Editing R documentation files</a>,
3154 Previous: <a rel="previous" accesskey="p" href="#ESS-for-the-S-family">ESS for the S family</a>,
3157 </div>
3161 <p><a name="index-editing-functions-121"></a>ESS provides facilities for editing S objects within your Emacs
3162 session. Most editing is performed on S functions, although in
3163 theory you may edit datasets as well. Edit buffers are always
3164 associated with files, although you may choose to make these files
3165 temporary if you wish. Alternatively, you may make use of a simple yet
3166 powerful mechanism for maintaining backups of text representations of
3167 S functions. Error-checking is performed when S code is loaded
3168 into the ESS process.
3173 <li><a accesskey="3" href="#Error-Checking">Error Checking</a>: Detecting errors in source files
3174 <li><a accesskey="4" href="#Evaluating-code">Evaluating code</a>: Sending code to the ESS process
3176 <li><a accesskey="6" href="#Other-edit-buffer-commands">Other edit buffer commands</a>: Commands for motion, completion and more
3178 <li><a accesskey="8" href="#Source-Directories">Source Directories</a>: Names and locations of dump files
3179 </ul>
3181 <!-- node-name, next, previous, up -->
3183 <p><hr>
3189 </div>
3194 To edit an S object, type
3196 <ul>
3198 <a name="index-ess_002ddump_002dobject_002dinto_002dedit_002dbuffer-123"></a>Edit an S object in its own edit buffer.
3199 </ul>
3202 prompted for an object to edit: you may either type in the name of an
3204 key),
3205 <a name="index-completion_002c-when-prompted-for-object-names-124"></a>or you may enter the name of a new object.
3206 <a name="index-creating-new-objects-125"></a><a name="index-new-objects_002c-creating-126"></a>A buffer will be created containing the text representation of the
3207 requested object or, if you entered the name of a non-existent object at
3209 <a name="index-ess_002dfunction_002dtemplate-127"></a>is non-<code>nil</code>, you will be presented with a template defined by that
3210 variable, which defaults to a skeleton function construct.
3212 <p>You may then edit the function as required. The edit buffer generated
3214 major mode which provides a number of commands to facilitate editing
3215 S source code. Commands are provided to intelligently indent S
3216 code, evaluate portions of S code and to move around S code
3217 constructs.
3219 <p><a name="index-dump-files-128"></a><a name="index-reverting-function-definitions-129"></a>Note: when you dump a file with <kbd>C-c C-d</kbd>, ESS first checks
3220 to see whether there already exists an edit buffer containing that
3221 object and, if so, pops you directly to that buffer. If not, ESS next
3222 checks whether there is a file in the appropriate place with the
3224 You can use this facility to return to an object you were editing in a
3225 previous session (and which possibly was never loaded to the S
3226 session). Finally, if both these tests fail, the ESS process is
3228 <a name="index-dump_0028_0029-130"></a>If you want to force ESS to ask the ESS process for the object's
3229 definition (say, to reformat an unmodified buffer or to revert back to
3230 S's idea of the object's definition) pass a prefix argument to
3233 <!-- node-name, next, previous, up -->
3235 <p><hr>
3241 </div>
3246 — into S is to load them in as source file, using S's
3249 loading source files (even files not created with ESS!) into the ESS
3250 process:
3252 <ul>
3254 <a name="index-ess_002dload_002dfile-131"></a>Loads a file into the ESS process using <code>source()</code>.
3257 <p class="noindent">After typing <kbd>C-c C-l</kbd> you will prompted for the name of the file to
3258 load into S; usually this is the current buffer's file which is the
3260 You will be asked to save the buffer first if it has been modified (this
3262 The file will then be loaded, and if it loads successfully you will be
3263 returned to the ESS process.
3265 <!-- node-name, next, previous, up -->
3267 <p><hr>
3273 </div>
3277 <p><a name="index-errors-133"></a><a name="index-parsing-errors-134"></a>If any errors occur when loading a file with <code>C-c C-l</code>, ESS will
3278 inform you of this fact. In this case, you can jump directly to the
3281 <a name="index-ess_002dparse_002derrors-135"></a>You will be returned to the offending file (loading it into a buffer if
3282 necessary) with point at the line S reported as containing the
3283 error. You may then correct the error, and reload the file. Note that
3284 none of the commands in an S source file will take effect if any
3285 part of the file contains errors.
3287 <p>Sometimes the error is not caused by a syntax error (loading a
3289 simply display a buffer containing S's error message. You can force
3294 <!-- node-name, next, previous, up -->
3296 <p><hr>
3302 </div>
3306 <p>Other commands are also available for evaluating portions of code in the
3307 S process. These commands cause the selected code to be evaluated
3308 directly by the ESS process as if you had typed them in at the
3310 whether both the commands and their output appear in the process buffer
3311 (as if you had typed in the commands yourself) or if the output alone is
3312 echoed. The behavior is controlled by the variable
3314 <a name="index-ess_002deval_002dvisibly_002dp-136"></a>(display output only). Passing a prefix argument (<kbd>C-u</kbd>) to any of
3315 the following commands, however, reverses the meaning of
3317 C-c C-j</kbd> echoes the current line of S (or other) code in the ESS
3318 process buffer, followed by its output. This method of evaluation is an
3320 <a name="index-source_0028_0029-137"></a><a name="index-echoing-commands-when-evaluating-138"></a><a name="index-evaluating-code-with-echoed-commands-139"></a>when you want the input as well as the output to be displayed. (You can
3322 set, except that prompts do not get displayed. ESS puts prompts in the
3323 right places.) The commands for evaluating code are:
3328 <a name="index-ess_002deval_002dline-141"></a>Send the line containing point to the ESS process.
3331 <a name="index-ess_002deval_002dline_002dand_002dgo-142"></a>As above, but returns you to the ESS process buffer as well.
3333 <li><kbd>C-c C-f</kbd> or <kbd>ESC C-x</kbd> (aka <kbd>M-C-x</kbd>) (<code>ess-eval-function</code>) <br>
3334 <a name="index-ess_002deval_002dfunction-143"></a>Send the S function containing point to the ESS process.
3337 <a name="index-ess_002deval_002dfunction_002dand_002dgo-144"></a>As above, but returns you to the ESS process buffer as well.
3340 <a name="index-ess_002deval_002dregion-145"></a>Send the text between point and mark to the ESS process.
3343 <a name="index-ess_002deval_002dregion_002dand_002dgo-146"></a>As above, but returns you to the ESS process buffer as well.
3346 <a name="index-ess_002deval_002dbuffer-147"></a>Send the contents of the edit buffer to the ESS process.
3349 <a name="index-ess_002deval_002dfunction_002dand_002dgo-148"></a>As above, but returns you to the ESS process buffer as well.
3352 <a name="index-ess_002deval_002dline_002dand_002dstep-149"></a><a name="index-stepping-through-code-150"></a><a name="index-debugging-S-functions-151"></a>Sends the current line to the ESS process, echoing it in the process
3353 buffer, and moves point to the next line. Useful when debugging for
3354 stepping through your code.
3355 </ul>
3358 should only be used for evaluating small portions of code for debugging
3359 purposes, or for generating transcripts from source files. When editing
3362 obsolete.
3364 <p>One final command is provided for spot-evaluations of S code:
3366 <ul>
3368 <a name="index-ess_002dexecute_002din_002dtb-152"></a>Prompt for an S expression and evaluate it. Displays result in a
3369 temporary buffer.
3370 </ul>
3374 <p>All the above commands are useful for evaluating small amounts of code
3375 and observing the results in the process buffer. A useful way to work
3376 is to divide the frame into two windows; one containing the source code
3377 and the other containing the process buffer. If you wish to make the
3378 process buffer scroll automatically when the output reaches the bottom
3379 of the window, you will need to set the variable
3382 <!-- node-name, next, previous, up -->
3384 <p><hr>
3386 Next: <a rel="next" accesskey="n" href="#Other-edit-buffer-commands">Other edit buffer commands</a>,
3390 </div>
3394 <p>ESS now provides a sophisticated mechanism for indenting S source
3395 code (thanks to Ken'ichi Shibayama). Compound statements (delimited by
3396 `<samp><span class="samp">{</span></samp>' and `<samp><span class="samp">}</span></samp>') are indented relative to their enclosing block.
3397 In addition, the braces have been electrified to automatically indent to
3398 the correct position when inserted, and optionally insert a newline at
3399 the appropriate place as well. Lines which continue an incomplete
3400 expression are indented relative to the first line of the expression.
3402 and loop constructs are all recognized and indented appropriately. User
3403 variables are provided to control the amount if indentation in each
3404 case, and there are also a number of predefined indentation styles to
3405 choose from.
3407 <p><a name="index-comments-in-S-153"></a>Comments are also handled specially by ESS, using an idea borrowed from
3408 the Emacs-Lisp indentation style. By default,
3410 are aligned to the beginning of the line. Comments beginning with
3411 `<samp><span class="samp">##</span></samp>' are aligned to the current level of indentation for the block
3412 containing the comment. Finally, comments beginning with `<samp><span class="samp">#</span></samp>' are
3413 aligned to a column on the right (the 40th column by default, but this
3415 <a name="index-comment_002dcolumn-154"></a>or just after the expression on the line containing the comment if it
3416 extends beyond the indentation column. You turn off the default
3417 behavior by adding the line
3418 <code>(setq ess-fancy-comments nil)</code> to your <samp><span class="file">.emacs</span></samp> file.
3420 The indentation commands provided by ESS are:
3422 <ul>
3424 Indents the current line as S code. If a prefix argument is given,
3425 all following lines which are part of the same (compound) expression are
3426 indented by the same amount (but relative indents are preserved).
3430 Insert a newline, and indent the next line. (Note that most keyboards
3433 <li><kbd>ESC C-q</kbd> aka <kbd>M-C-q</kbd> aka <kbd>C-M-q</kbd> (<code>ess-indent-exp</code>) <br>
3434 Indents each line in the S (compound) expression which follows point.
3435 Very useful for beautifying your S code.
3438 The braces automatically indent to the correct position when typed.
3441 Indents an existing comment line appropriately, or inserts an
3442 appropriate comment marker.
3445 Set the formatting style in this buffer to be one of the predefined
3446 styles: <code>GNU</code>, <code>BSD</code>, <code>K&R</code>, <code>CLB</code>, and <code>C++</code>.
3448 variables (unless they have been modified in your <samp><span class="file">.emacs</span></samp> file.)
3449 <a name="index-g_t_0040file_007b_002eemacs_007d-file-158"></a>This command causes all of the formatting variables to be buffer-local.
3450 </ul>
3452 <!-- node-name, next, previous, up -->
3454 <p><hr>
3460 </div>
3464 <p>A number of commands are provided to move across function definitions
3465 in the edit buffer:
3466 <ul>
3468 <a name="index-ess_002dbeginning_002dof_002dfunction-159"></a>Moves point to the beginning of the function containing point.
3471 <a name="index-ess_002dend_002dof_002dfunction-160"></a>Moves point to the end of the function containing point.
3474 Places point at the beginning of the S function containing point, and
3475 mark at the end.
3476 </ul>
3477 Don't forget the usual Emacs commands for moving over balanced
3480 <p><a name="index-completion-in-edit-buffer-161"></a>Completion is provided in the edit buffer in a similar fashion to the
3484 however that completion is only provided over globally known S objects
3486 functions or other variables local to the function you are editing.
3488 <p>Finally, two commands are provided for returning to the ESS process buffer:
3490 <ul>
3492 <a name="index-ess_002dswitch_002dto_002dend_002dof_002dESS-162"></a>Returns you to the ESS process buffer, placing point at the end of the
3493 buffer.
3496 <a name="index-ess_002dswitch_002dto_002dESS-163"></a>Also returns to to the ESS process buffer, but leaves point where it was.
3497 </ul>
3499 <p>In addition some commands available in the process buffer are also
3500 available in the edit buffer. You can still read help files with
3503 for more details on these commands.
3505 <!-- node-name, next, previous, up -->
3507 <p><hr>
3510 Previous: <a rel="previous" accesskey="p" href="#Other-edit-buffer-commands">Other edit buffer commands</a>,
3513 </div>
3520 after use, or kept as a backup file or as a means of keeping several
3521 versions of an S function.
3525 — User Option: <b>ess-delete-dump-files</b><var><a name="index-ess_002ddelete_002ddump_002dfiles-165"></a></var><br>
3527 immediately after they are created by the ess-process.
3528 </p></blockquote></div>
3530 <p>Since immediately after S dumps an object's definition to a disk
3531 file the source code on disk corresponds exactly to S's idea of the
3532 object's definition, the disk file isn't needed; deleting it now has the
3534 just wanted to look at the definition of one of the standard S
3535 functions) the source dump file won't be left around when you kill the
3536 buffer. Note that this variable only applies to files generated with
3541 — User Option: <b>ess-keep-dump-files</b><var><a name="index-ess_002dkeep_002ddump_002dfiles-166"></a></var><br>
3542 <blockquote><p>Option controlling what to do with the dump file after an object has
3547 buffer-local.
3548 </p></blockquote></div>
3550 <p>After an object has been successfully (i.e. without error) loaded
3552 exactly (well, almost — see below) to S's record of the object's
3553 definition, and so some people prefer to delete the disk file rather
3554 than unnecessarily use up space. This option allows you to do just
3555 that.
3557 <p><a name="index-comments-167"></a><a name="index-project-work-in-S-168"></a><a name="index-historic-backups-169"></a>If the value of <code>ess-keep-dump-files</code> is <code>t</code>, dump files are
3558 never deleted after they are loaded. Thus you can maintain a complete
3559 text record of the functions you have edited within ESS. Backup files
3560 are kept as usual, and so by using the Emacs numbered backup facility —
3562 record of function definitions. Another possibility is to maintain the
3563 files with a version-control system such as RCS See <a href="emacs.html#Version-Control">Version Control</a>. As long as a dump file exists in the appropriate place for a
3565 file for editing (unless a prefix argument is given) — the ESS
3567 function definition as a means of documentation that does not clutter
3568 the S object itself. Another useful feature is that you may format
3569 the code in any fashion you please without S re-indenting the code
3570 every time you edit it. These features are particularly useful for
3571 project-based work.
3576 to any other file you load (say, a source file of function
3577 definitions), and so can be dangerous to use unless you are careful.
3580 Local Variables section of the file See <a href="emacs.html#File-Variables">Local Variables in Files</a>.
3583 means that ESS will always ask for confirmation before deleting the
3584 file. Since this can get annoying if you always want to delete dump
3588 Emacs session, but query for any other file. Note that in any case you
3589 will only be asked for confirmation once per file, and your answer is
3590 remembered for the rest of the Emacs session.
3592 <p>Note that in all cases, if an error (such as a syntax error) is detected
3594 deleted. This is so that you can edit the file in a new Emacs session
3595 if you happen to quit Emacs before correcting the error.
3597 <p><a name="index-autosaving-170"></a>Dump buffers are always autosaved, regardless of the value of
3600 <!-- node-name, next, previous, up -->
3602 <p><hr>
3607 </div>
3611 <p><a name="index-dump-file-names-171"></a>Every dump file should be given a unique file name, usually the dumped
3612 object name with some additions.
3615 — User Option: <b>ess-dump-filename-template</b><var><a name="index-ess_002ddump_002dfilename_002dtemplate-172"></a></var><br>
3617 object name.
3618 </p></blockquote></div>
3620 <p class="noindent">By default, dump file names are the user name, followed by `<samp><span class="samp">.</span></samp>' and
3621 the object and ending with `<samp><span class="samp">.S</span></samp>'. Thus if user <code>joe</code> dumps the
3622 object <code>myfun</code> the dump file will have name <samp><span class="file">joe.myfun.S</span></samp>.
3623 The username part is included to avoid clashes when dumping into a
3624 publicly-writable directory, such as <samp><span class="file">/tmp</span></samp>; you may wish to remove
3625 this part if you are dumping into a directory owned by you.
3627 <p><a name="index-dump-file-directories-173"></a>You may also specify the directory in which dump files are written:
3630 — User Option: <b>ess-source-directory</b><var><a name="index-ess_002dsource_002ddirectory-174"></a></var><br>
3631 <blockquote><p>Directory name (ending in a slash) where S dump files are to be written.
3632 </p></blockquote></div>
3634 <p>By default, dump files are always written to <samp><span class="file">/tmp</span></samp>, which is fine
3636 files, then you will probably want to keep them somewhere in your home
3637 directory, say <samp><span class="file">~/S-source</span></samp>. This could be achieved by including
3641 </pre>
3642 <p>If you would prefer to keep your dump files in separate directories
3643 depending on the value of some variable, ESS provides a facility for
3645 expression which evaluates to a directory name, you have a great deal of
3646 flexibility in selecting the directory for a particular source file to
3647 appear in. The lambda expression is evaluated with the process buffer
3648 as the current buffer and so you can use the variables local to that
3649 buffer to make your choice. For example, the following expression
3650 causes source files to be saved in the subdirectory <samp><span class="file">Src</span></samp> of the
3651 directory the ESS process was run in.
3654 (lambda ()
3655 (concat ess-directory "Src/")))
3656 </pre>
3657 <p class="noindent"><a name="index-ess_002ddirectory-176"></a>(<code>ess-directory</code> is a buffer-local variable in process buffers
3658 which records the directory the ESS process was run from.) This is
3659 useful if you keep your dump files and you often edit objects with the
3660 same name in different ESS processes. Alternatively, if you often
3661 change your S working directory during an S session, you may
3662 like to keep dump files in some subdirectory of the directory pointed to
3663 by the first element of the current search list. This way you can edit
3664 objects of the same name in different directories during the one S
3665 session:
3668 (lambda ()
3669 (file-name-as-directory
3670 (expand-file-name (concat
3671 (car ess-search-list)
3672 "/.Src")))))
3673 </pre>
3675 If the directory generated by the lambda function does not exist but can
3676 be created, you will be asked whether you wish to create the directory.
3677 If you choose not to, or the directory cannot be created, you will not
3678 be able to edit functions.
3681 <p><hr>
3687 </div>
3692 files. R objects are documented in files written in Rd format, a
3693 simple markup language closely resembling (La)TeX, which can be
3698 <p>Visiting an Rd file as characterized by its extension <samp><span class="file">Rd</span></samp> will
3699 activate Rd Mode, which provides several facilities for making editing R
3700 documentation files more convenient, by helping with indentation,
3701 insertions, even doing some of the typing for you (with Abbrev Mode),
3702 and by showing Rd keywords, strings, etc. in different faces (with
3703 Font Lock Mode).
3705 <p>Note that R also accepts Rd files with extension <samp><span class="file">rd</span></samp>; to activate
3709 </pre>
3712 <p>In Rd mode, the following special Emacs commands can be used in addition
3713 to the standard Emacs commands.
3715 <dl>
3718 <br><dt><kbd>LFD</kbd><dt><kbd>RET</kbd><dd>Reindent the current line, insert a newline and indent the new line
3725 <br><dt><kbd>C-c C-e</kbd><dd>Insert a “skeleton” with Rd markup for at least all mandatory entries
3729 already has all information filled in which can be obtained from the
3730 object).
3732 <br><dt><kbd>C-c C-f</kbd><dd>Insert “font” specifiers for some of the Rd markup commands markup
3733 available for emphasizing or quoting text, including markup for URLs and
3736 currently, not all of the Rd text markup as described in section
3740 <br><dt><kbd>C-c C-j</kbd><dd>Insert a suitably indented `<samp><span class="samp">\item{</span></samp>' on the next line
3743 <br><dt><kbd>C-c C-p</kbd><dd>Preview a plain text version (“help file”, see <a href="#Help">Help</a>) generated
3745 </dl>
3747 <p>In addition, when editing Rd files one can interact with a running R
3748 process in a similar way as when editing R language files. E.g.,
3750 the current line to the R process for evaluation. This interaction is
3751 particularly useful when editing the examples in the Rd file. See
3754 <p>Rd mode also provides access to abbreviations for most of the Rd markup
3756 list all available abbrevs. Note that all Rd abbrevs start with a grave
3757 accent.
3759 <p>Rd mode can be customized via the following variables.
3761 <dl>
3763 <br><dt><code>Rd-indent-level</code><dd>The indentation of Rd code with respect to containing blocks. Default
3764 is 2.
3765 <br><dt><code>Rd-to-help-command</code><dd>The shell command used for converting Rd source to help text. Default
3767 </dl>
3769 <p>To automatically turn on the abbrev and font-lock features of Rd mode,
3770 add the following lines to one of your Emacs startup files:
3773 (lambda ()
3774 (abbrev-mode 1)
3775 (font-lock-mode 1)))
3776 </pre>
3777 <!-- node-name, next, previous, up -->
3779 <p><hr>
3782 Previous: <a rel="previous" accesskey="p" href="#Editing-R-documentation-files">Editing R documentation files</a>,
3785 </div>
3790 ESS provides an easy-to-use facility for reading S help files from
3791 within Emacs. From within the ESS process buffer or any ESS edit
3793 <a name="index-ess_002ddisplay_002dhelp_002don_002dobject-181"></a>will prompt you for the name of an object for which you would like
3794 documentation. Completion is provided over all objects which have help
3795 files.
3797 <p>If the requested object has documentation, you will be popped into a
3799 This buffer is placed in a special `S Help' mode which disables the
3800 usual editing commands but which provides a number of keys for paging
3801 through the help file:
3803 <ul>
3804 Help commands:
3807 <a name="index-ess_002ddescribe_002dhelp_002dmode-182"></a>Pops up a help buffer with a list of the commands available in S help
3808 mode.
3811 <a name="index-ess_002ddisplay_002dhelp_002don_002dobject-183"></a>Pop up a help buffer for a different object
3813 <p>Paging commands:
3815 <p><a name="index-paging-commands-in-help-buffers-184"></a><li><kbd>b</kbd> or <kbd>DEL</kbd> (<code>scroll-down</code>) <br>
3816 Move one page backwards through the help file.
3819 Move one page forwards through the help file.
3821 <li><kbd>></kbd> (<code>beginning-of-buffer</code>) and <kbd><</kbd> (<code>end-of-buffer</code>)
3822 <br>
3823 Move to the beginning and end of the help file, respectively.
3825 <p>Section-based motion commands:
3829 <a name="index-ess_002dskip_002dto_002dnext_002dsection-185"></a><a name="index-ess_002dskip_002dto_002dprevious_002dsection-186"></a>section header in the help file, respectively. A section header
3830 consists of a number of capitalized words, followed by a colon.
3833 will jump to a particular section in the help file.
3834 Note that R uses capitalized instead of all-capital section headers,
3835 e.g., `<samp><span class="samp">Description:</span></samp>' instead of `<samp><span class="samp">DESCRIPTION:</span></samp>' and also
3836 only some versions of S(-plus) have
3837 sections `<samp><span class="samp">BACKGROUND</span></samp>', `<samp><span class="samp">BUGS</span></samp>', `<samp><span class="samp">OPTIONAL ARGUMENTS</span></samp>',
3838 `<samp><span class="samp">REQUIRED ARGUMENTS</span></samp>', and `<samp><span class="samp">SIDE EFFECTS</span></samp>'.
3839 <!-- The bindings are all in ../lisp/essl-s.el -->
3840 <!-- ess-help-*-sec-keys-alist -->
3841 <!-- S-plus only: -->
3842 <!-- @item b BACKGROUND: -->
3843 <!-- @item B BUGS: -->
3844 <!-- @item O OPTIONAL ARGUMENTS: -->
3845 <!-- @item R REQUIRED ARGUMENTS: -->
3847 <!-- S and S-plus only: -->
3848 <!-- @item S SIDE EFFECTS: -->
3851 <dl>
3884 <br><dt>`<samp><span class="samp">?</span></samp>'<dd>Pops up a help buffer with a list of the defined section motion keys.
3885 </dl>
3887 <p>Miscellaneous:
3890 <a name="index-ess_002deval_002dline_002dand_002dstep-188"></a>Evaluates the current line in the ESS process, and moves to the next
3891 line. Useful for running examples in help files.
3894 <a name="index-ess_002deval_002dregion-189"></a>Send the contents of the current region to the ESS process. Useful
3895 for running examples in help files.
3900 <p>Quit commands:
3903 <a name="index-ess_002dswitch_002dto_002dend_002dof_002dESS-190"></a>Returns to the ESS process buffer in another window, leaving the
3904 help window visible.
3907 Kills the help buffer.
3910 Return to the ESS process, killing this help buffer.
3911 </ul>
3913 <p>In addition, all of the ESS commands available in the edit buffers are
3915 usual (non-editing) Emacs commands are available, and for convenience
3918 <p>If a help buffer already exists for an object for which help is
3919 requested, that buffer is popped to immediately; the ESS process is
3920 not consulted at all. If the contents of the help file have changed,
3921 you either need to kill the help buffer first, or pass a prefix argument
3924 <p>Help buffers are marked as temporary buffers in ESS, and are deleted
3927 <p>Help buffers normally appear in another window within the current
3928 frame. If you wish help buffers to appear in their own frame (either
3929 one per help buffer, or one for all help buffers), you can customize the
3932 <p><a name="index-ess_002dquit-191"></a><a name="index-ess_002dcleanup-192"></a><a name="index-temporary-buffers-193"></a>
3933 <!-- node-name, next, previous, up -->
3935 <p><hr>
3941 </div>
3946 <li><a accesskey="1" href="#ESS_0028SAS_0029_002d_002dDesign-philosophy">ESS(SAS)--Design philosophy</a>
3947 <li><a accesskey="2" href="#ESS_0028SAS_0029_002d_002dEditing-files">ESS(SAS)--Editing files</a>
3949 <li><a accesskey="4" href="#ESS_0028SAS_0029_002d_002dBatch-SAS-processes">ESS(SAS)--Batch SAS processes</a>
3950 <li><a accesskey="5" href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">ESS(SAS)--Function keys for batch processing</a>
3951 <li><a accesskey="6" href="#iESS_0028SAS_0029_002d_002dInteractive-SAS-processes">iESS(SAS)--Interactive SAS processes</a>
3952 <li><a accesskey="7" href="#iESS_0028SAS_0029_002d_002dCommon-problems">iESS(SAS)--Common problems</a>
3955 </ul>
3957 <p><acronym>ESS[SAS]</acronym> was designed for use with <acronym>SAS</acronym><!-- /@w -->. It is descended from emacs
3958 macros developed by John Sall for editing <acronym>SAS</acronym><!-- /@w --> programs and <code>SAS-mode</code> by
3959 Tom Cook. Those editing features and new advanced features are part of
3960 <acronym>ESS[SAS]</acronym>. The user interface of <acronym>ESS[SAS]</acronym> has similarities with <acronym>ESS[S]</acronym>
3963 <!-- node-name, next, previous, up -->
3965 <p><hr>
3968 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dEditing-files">ESS(SAS)--Editing files</a>,
3972 </div>
3976 <p><acronym>ESS[SAS]</acronym> was designed to aid the user in writing and maintaining <acronym>SAS</acronym><!-- /@w -->
3977 programs, such as <samp><var>foo</var><span class="file">.sas</span></samp>. Both interactive and batch
3982 <li>The emacs text editor provides a powerful and flexible development
3983 environment for programming languages. These features are a boon to all
3984 programmers and, with the help of <acronym>ESS[SAS]</acronym>, to <acronym>SAS</acronym><!-- /@w --> users as well.
3985 <li>Although a departure from <acronym>SAS</acronym><!-- /@w --> Display Manager, <acronym>ESS[SAS]</acronym> provides
3987 Also, inconvenient <acronym>SAS</acronym><!-- /@w --> Display Manager features, like remote submission
3988 and syntax highlighting, are provided transparently; appealing to
3990 </ol>
3992 <!-- node-name, next, previous, up -->
3994 <p><hr>
3997 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dTAB-key">ESS(SAS)--TAB key</a>,
3998 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dDesign-philosophy">ESS(SAS)--Design philosophy</a>,
4001 </div>
4005 <p><acronym>ESS[SAS]</acronym> is the mode for editing <acronym>SAS</acronym><!-- /@w --> language files. This mode handles:
4007 <ul>
4009 <li>color and font choices based on syntax.
4010 <li>ability to save and submit the file you are working on as a batch
4011 <acronym>SAS</acronym><!-- /@w --> process with a single keypress and to continue editing while it is runs
4012 in the background.
4013 <li>capability of killing the batch <acronym>SAS</acronym><!-- /@w --> process through the <samp><span class="file">*shell*</span></samp> buffer or
4015 <li>single keypress navigation of <samp><span class="file">.sas</span></samp>, <samp><span class="file">.log</span></samp> and <samp><span class="file">.lst</span></samp> files
4016 (<samp><span class="file">.log</span></samp> and <samp><span class="file">.lst</span></samp> files are refreshed with each keypress).
4017 <li>ability to send the contents of an entire buffer, a highlighted region,
4019 <li>ability to switch between processes which would be the target of the
4020 buffer (for the above).
4021 </ul>
4023 <p><acronym>ESS[SAS]</acronym> is automatically turned on when editing a file with a <samp><span class="file">.sas</span></samp>
4025 keys can be enabled to use the same function keys that
4026 the <acronym>SAS</acronym><!-- /@w --> Display Manager does. The interactive capabilities of <acronym>ESS</acronym> require you
4027 to start an inferior <acronym>SAS</acronym><!-- /@w --> process with <kbd>M-x SAS</kbd><!-- /@w -->
4028 (See <a href="#iESS_0028SAS_0029_002d_002dInteractive-SAS-processes">iESS(SAS)–Interactive SAS processes</a>.)
4030 <p>At this writing, the indenting and syntax highlighting are generally
4032 first line is highlighted; for <samp><span class="file">.log</span></samp> files, only the first line of a
4033 <code>NOTE:</code>, <code>WARNING:</code> or <code>ERROR:</code> message is highlighted; unmatched
4037 <!-- node-name, next, previous, up -->
4039 <p><hr>
4042 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dBatch-SAS-processes">ESS(SAS)--Batch SAS processes</a>,
4043 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dEditing-files">ESS(SAS)--Editing files</a>,
4046 </div>
4051 function is used to syntactically indent <acronym>SAS</acronym><!-- /@w --> code so <code>PROC</code> and <code>RUN</code> are in
4052 the left margin, other statements are indented <code>sas-indent-width</code> spaces from the margin,
4053 continuation lines are indented <code>sas-indent-width</code> spaces in from the beginning column of
4054 that statement. This is the type of functionality that emacs provides
4055 in most programming language modes. This functionality is equivalent to
4058 </pre>
4060 as it does in <acronym>SAS</acronym><!-- /@w --> Display Manager, i.e. move the cursor to the next stop.
4061 The alternate behavior also provides a "TAB" backwards, <kbd>C-<TAB></kbd><!-- /@w -->, that
4062 moves the cursor to the stop to the left and deletes any characters
4063 between them. This functionality is obtained by uncommenting the
4066 </pre>
4067 <p>Under the alternate behavior, <TAB> is bound to <kbd>M-x tab-to-tab-stop</kbd><!-- /@w -->
4070 <!-- node-name, next, previous, up -->
4072 <p><hr>
4075 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">ESS(SAS)--Function keys for batch processing</a>,
4076 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dTAB-key">ESS(SAS)--TAB key</a>,
4079 </div>
4083 <p>Submission of a <acronym>SAS</acronym><!-- /@w --> batch job is dependent on your environment.
4087 a <acronym>UNIX</acronym>-imitating shell; otherwise <code>'ms-dos</code> for an <acronym>MS-DOS</acronym>
4090 if the <acronym>SAS</acronym><!-- /@w --> batch job needs to run on a remote machine rather than your
4091 local machine. This works transparently if you are editing the remote file
4092 via ange-ftp/EFS or tramp. Note that
4095 and it is assumed that no password is necessary, i.e. you are using
4097 Local Variables below if you need to change the default).
4099 <p>However, if you are editing the file locally and transferring it back and
4100 forth with Kermit, you need some additional steps. First, start Kermit
4101 locally before remotely logging in. Open a local copy of the file with the
4104 the contents of the remote file into your local copy. If you transfer
4105 files with Kermit manually in a <samp><span class="file">*shell*</span></samp> buffer, then note that the
4106 Kermit escape sequence is <kbd>C-q C- c</kbd><!-- /@w --> rather than <kbd>C- c</kbd><!-- /@w --> which
4107 it would be in an ordinary terminal application, i.e. not in an emacs
4108 buffer. Lastly, note that the remote Kermit command is specified by
4117 buffer-local. Conveniently, it can be set at the end of the program:
4119 Local variables:
4120 ess-sas-submit-command: "sas8"
4121 End:
4122 </pre>
4125 (the last of which is also buffer-local).
4126 Here are some examples for your <samp><span class="file">~/.emacs</span></samp> or <samp><span class="file">~/.xemacs/init.el</span></samp>
4129 (setq ess-sas-submit-pre-command "nohup")
4130 ;'sh default
4131 (setq ess-sas-submit-post-command "-rsasuser &")
4132 ;'sh example
4133 (setq-default ess-sas-submit-command "/usr/local/sas/sas")
4134 ;'ms-dos default
4135 (setq ess-sas-submit-pre-command "start")
4136 ;'ms-dos default
4137 (setq ess-sas-submit-post-command "-rsasuser -icon")
4138 ;Windows example
4139 (setq-default ess-sas-submit-command "c:/progra~1/sas/sas.exe")
4140 ;Windows example
4141 (setq-default ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe")
4142 </pre>
4143 <p>There is a built-in delay before a batch <acronym>SAS</acronym><!-- /@w --> job is submitted when using
4145 since the shell might not be ready to receive a command. This delay is
4146 currently set high enough so as not to be a problem. But, there may be
4147 cases when it needs to be set higher, or could be set much lower to
4148 speed things up. You can over-ride the default in your <samp><span class="file">~/.emacs</span></samp> or <samp><span class="file">~/.xemacs/init.el</span></samp> file by:
4150 </pre>
4155 <samp><var>foo</var><span class="file">.sas</span></samp> will be in <acronym>ESS[SAS]</acronym> mode. Edit as appropriate, then save and
4158 </pre>
4159 <p>The job runs in the <samp><span class="file">*shell*</span></samp> buffer while you continue to edit
4160 <samp><var>foo</var><span class="file">.sas</span></samp>. If <code>ess-sas-submit-method</code> is <code>'sh</code>, then the
4161 message buffer will display the shell notification when the
4165 </pre>
4166 <p>Terminating a <acronym>SAS</acronym><!-- /@w --> batch in the <samp><span class="file">*shell*</span></samp> buffer.
4168 </pre>
4169 <p>You may want to visit the <samp><span class="file">.log</span></samp> (whether the job is still running
4170 or it is finished) and check for error messages. The <samp><span class="file">.log</span></samp> will be
4171 refreshed and you will be placed in it's buffer. You will be
4172 taken to the first error message, if any.
4174 </pre>
4175 <p>Goto the next error message, if any.
4177 </pre>
4178 <p>Now, `<samp><span class="samp">refresh</span></samp>' the <samp><span class="file">.lst</span></samp> and go to it's buffer.
4180 </pre>
4181 <p>If you wish to make changes, go to the <samp><span class="file">.sas</span></samp> file with.
4183 </pre>
4184 <p>Make your editing changes and submit again.
4186 </pre>
4187 <!-- node-name, next, previous, up -->
4189 <p><hr>
4192 Next: <a rel="next" accesskey="n" href="#iESS_0028SAS_0029_002d_002dInteractive-SAS-processes">iESS(SAS)--Interactive SAS processes</a>,
4193 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dBatch-SAS-processes">ESS(SAS)--Batch SAS processes</a>,
4196 </div>
4201 is unavoidably complex, but the usage of function keys is simple.
4202 There are five distinct options:
4205 commands. This is in accordance with the GNU Elisp Coding Standards
4207 available to the user.
4211 the option of binding elisp commands to these keys. Users who are
4212 familiar with <acronym>SAS</acronym><!-- /@w --> will, most likely, want to duplicate the function key
4213 capabilities of the <acronym>SAS</acronym><!-- /@w --> Display Manager. There are four options (noted
4214 in parentheses).
4217 <li><acronym>SAS</acronym><!-- /@w --> Display Manager has different function key definitions for
4221 are associated with <acronym>ESS[SAS]</acronym> as specified in your <code>auto-mode-alist</code>.
4222 </ol>
4224 <p>The distinction between local and global is subtle. If you want the
4225 <acronym>ESS[SAS]</acronym> definitions to work when you are in the <samp><span class="file">*shell*</span></samp> buffer or when
4227 you will most likely want to use the global definitions. If you want
4228 your function keys to understand <acronym>SAS</acronym><!-- /@w --> batch commands when you are editing
4229 <acronym>SAS</acronym><!-- /@w --> files, and to behave normally when editing other files, then you
4230 will choose the local definitions. The option can be chosen by the
4235 following lines in your <samp><span class="file">ess-site.el</span></samp>. <acronym>ESS[SAS]</acronym> function keys are
4239 ;;3; (setq ess-sas-local-pc-keys t)
4240 ;;4; (setq ess-sas-global-unix-keys t)
4241 ;;5; (setq ess-sas-global-pc-keys t)
4242 </pre>
4243 <p>The names <code>-unix-</code> and <code>-pc-</code> have nothing to do with the operating system
4244 that you are running. Rather, they mimic the definitions that the <acronym>SAS</acronym><!-- /@w -->
4245 Display Manager uses by default on those platforms.
4247 <li>If your site installation has configured the keys contrary to your
4248 liking, then you must call the appropriate function.
4250 (ess-sas-global-pc-keys)
4251 </pre>
4252 </ol>
4254 <p>Finally, we get to what the function keys actually do. You may recognize
4255 some of the nicknames as <acronym>SAS</acronym><!-- /@w --> Display Manager commands (they are in all
4256 capitals).
4258 <p><table summary=""><tr align="left"><td valign="top"><acronym>UNIX</acronym> </td><td valign="top"><acronym>PC</acronym> </td><td valign="top">Nickname
4259 <br></td></tr><tr align="left"><td valign="top"><F2> </td><td valign="top"><F2> </td><td valign="top">`<samp><span class="samp">refresh</span></samp>'
4261 revert the current buffer with the file of the same
4262 name if the file is newer than the buffer
4263 <br></td></tr><tr align="left"><td valign="top"><F3> </td><td valign="top"><F8> </td><td valign="top"><code>SUBMIT</code>
4265 save the current <samp><span class="file">.sas</span></samp> file (which is either the <samp><span class="file">.sas</span></samp>
4267 with the <samp><span class="file">.lst</span></samp> or <samp><span class="file">.log</span></samp> file in the current buffer)
4269 <br></td></tr><tr align="left"><td valign="top"><F4> </td><td valign="top"><F5> </td><td valign="top"><code>PROGRAM</code>
4272 <br></td></tr><tr align="left"><td valign="top"><F5> </td><td valign="top"><F6> </td><td valign="top"><code>LOG</code>
4274 switch buffer to <samp><span class="file">.log</span></samp> file, `<samp><span class="samp">refresh</span></samp>' and goto next
4275 error message, if any
4276 <br></td></tr><tr align="left"><td valign="top"><F6> </td><td valign="top"><F7> </td><td valign="top"><code>OUTPUT</code>
4278 switch buffer to <samp><span class="file">.lst</span></samp> file and `<samp><span class="samp">refresh</span></samp>'
4279 <br></td></tr><tr align="left"><td valign="top"><F7> </td><td valign="top"><F4> </td><td valign="top">`<samp><span class="samp">filetype-1</span></samp>'
4281 switch buffer to `<samp><span class="samp">filetype-1</span></samp>' (defaults to <samp><span class="file">.txt</span></samp>) file
4283 <br></td></tr><tr align="left"><td valign="top"><F8> </td><td valign="top"><F3> </td><td valign="top">`<samp><span class="samp">shell</span></samp>'
4286 <br></td></tr><tr align="left"><td valign="top"><F9> </td><td valign="top"><F9> </td><td valign="top"><code>VIEWTABLE</code>
4289 dataset near point
4290 <br></td></tr><tr align="left"><td valign="top"><F10> </td><td valign="top"><F10> </td><td valign="top">toggle-log
4292 toggle <acronym>ESS[SAS]</acronym> for <samp><span class="file">.log</span></samp> files; useful for certain
4293 debugging situations
4294 <br></td></tr><tr align="left"><td valign="top"><F11> </td><td valign="top"><F11> </td><td valign="top">`<samp><span class="samp">filetype-2</span></samp>'
4296 switch buffer to `<samp><span class="samp">filetype-2</span></samp>' (defaults to <samp><span class="file">.dat</span></samp>) file
4298 <br></td></tr><tr align="left"><td valign="top"><F12> </td><td valign="top"><F12> </td><td valign="top">viewgraph
4301 or with an external viewer
4302 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F1></kbd> </td><td valign="top"><kbd>C-<F1></kbd> </td><td valign="top">rtf-portrait
4306 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F2></kbd> </td><td valign="top"><kbd>C-<F2></kbd> </td><td valign="top">rtf-landscape
4310 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F3></kbd> </td><td valign="top"><kbd>C-<F8></kbd> </td><td valign="top">submit-region
4313 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F5></kbd> </td><td valign="top"><kbd>C-<F6></kbd> </td><td valign="top">append-to-log
4315 append <samp><span class="file">ess-temp.log</span></samp> to the current <samp><span class="file">.log</span></samp> file
4316 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F6></kbd> </td><td valign="top"><kbd>C-<F7></kbd> </td><td valign="top">append-to-output
4318 append <samp><span class="file">ess-temp.lst</span></samp> to the current <samp><span class="file">.lst</span></samp> file
4319 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F9></kbd> </td><td valign="top"><kbd>C-<F9></kbd> </td><td valign="top"><code>INSIGHT</code>
4321 open an interactive <code>PROC INSIGHT</code> session on the <acronym>SAS</acronym><!-- /@w -->
4322 dataset near point
4323 <br></td></tr><tr align="left"><td valign="top"><kbd>C-<F10></kbd> </td><td valign="top"><kbd>C-<F10></kbd> </td><td valign="top">toggle-listing
4325 toggle <acronym>ESS[SAS]</acronym> for <samp><span class="file">.lst</span></samp> files; useful for toggling
4326 read-only
4327 <br></td></tr></table>
4329 <p><code>SUBMIT</code>, <code>PROGRAM</code>, <code>LOG</code> and <code>OUTPUT</code> need no further
4330 explanation since they mimic the <acronym>SAS</acronym><!-- /@w --> Display Manager commands and
4331 related function key definitions. However, six other keys have been
4332 provided for convenience and are described below.
4334 <p>`<samp><span class="samp">shell</span></samp>' switches you to the <samp><span class="file">*shell*</span></samp> buffer where you can
4335 interact with your operating system. This is especially helpful if you
4336 would like to kill a <acronym>SAS</acronym><!-- /@w --> batch job. You can specify a different buffer
4337 name to associate with a <acronym>SAS</acronym><!-- /@w --> batch job (besides <samp><span class="file">*shell*</span></samp>) with the
4339 multiple buffers running <acronym>SAS</acronym><!-- /@w --> batch jobs on multiple local/remote
4340 computers that may rely on different methods specified by the buffer-local
4343 <p><F2> performs the `<samp><span class="samp">refresh</span></samp>' operation on the current buffer.
4344 `<samp><span class="samp">refresh</span></samp>' compares the buffer's last modified date/time with the
4345 file's last modified date/time and replaces the buffer with the file if the
4346 file is newer. This is the same operation that is automatically performed
4347 when <code>LOG</code>, <code>OUTPUT</code>, `<samp><span class="samp">filetype-1</span></samp>' or <F11> are pressed.
4349 <p>`<samp><span class="samp">filetype-1</span></samp>' switches you to a file with the same file name as your <samp><span class="file">.sas</span></samp>
4350 file, but with a different extension (<samp><span class="file">.txt</span></samp> by default) and performs
4351 `<samp><span class="samp">refresh</span></samp>'. You can over-ride the default extension; for example in your
4352 <samp><span class="file">~/.emacs</span></samp> or <samp><span class="file">~/.xemacs/init.el</span></samp> file:
4354 </pre>
4355 <p><F9> will prompt you for the name of a permanent <acronym>SAS</acronym><!-- /@w --> dataset near
4357 <acronym>SAS</acronym><!-- /@w --> batch command-line with <code>ess-sas-data-view-submit-options</code>.
4358 For controlling the <acronym>SAS</acronym><!-- /@w --> batch commands, you have the global variables
4362 <acronym>SAS</acronym><!-- /@w --> <code>LIBNAME</code> defined in <samp><span class="file">~/autoexec.sas</span></samp>, then the defaults
4363 for these variables should be sufficient.
4366 <acronym>SAS</acronym><!-- /@w --> dataset near point to be opened for viewing by <code>PROC INSIGHT</code>.
4368 <code>ess-sas-data-view-submit-options</code>. For controlling the <acronym>SAS</acronym><!-- /@w --> batch
4373 <p><F10> toggles <acronym>ESS[SAS]</acronym> mode for <samp><span class="file">.log</span></samp> files which is off by default
4375 highlighting can be helpful in certain debugging situations, but large
4378 <p><F11> is the same as `<samp><span class="samp">filetype-1</span></samp>' except it is <samp><span class="file">.dat</span></samp> by default.
4380 <p><F12> will prompt you for the name of a <code>GSASFILE</code> near the point in <samp><span class="file">.log</span></samp> to
4381 be opened for viewing either with emacs or with an external viewer.
4382 Depending on your version of emacs and the operating system you are
4383 using, emacs may support <samp><span class="file">.gif</span></samp> and <samp><span class="file">.jpg</span></samp> files internally. You may need
4384 to change the following variables for your own situation.
4386 file types defined via file name extensions.
4389 exceptions to the default; i.e. file types and their associated
4390 viewers which will be used rather than the default viewer.
4392 "[pP][dD][fF]\\|[gG][iI][fF]\\|[jJ][pP][eE]?[gG]\\|"
4393 "[tT][iI][fF][fF]?\\)")) ;; default
4394 (setq ess-sas-graph-view-viewer-default "kodakimg") ;; Windows default
4395 (setq ess-sas-graph-view-viewer-default "sdtimage") ;; Solaris default
4396 (setq ess-sas-graph-view-viewer-alist
4398 </pre>
4399 <p><kbd>C-<F2></kbd><!-- /@w --> produces US landscape by default, however, it can produce A4
4402 (define-key sas-mode-local-map [(control f2)] 'ess-sas-rtf-a4-landscape)
4403 </pre>
4404 <!-- node-name, next, previous, up -->
4406 <p><hr>
4409 Next: <a rel="next" accesskey="n" href="#iESS_0028SAS_0029_002d_002dCommon-problems">iESS(SAS)--Common problems</a>,
4410 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">ESS(SAS)--Function keys for batch processing</a>,
4413 </div>
4417 <p>Inferior <acronym>ESS</acronym> (i<acronym>ESS</acronym><!-- /@w -->) is the method for interfacing with interactive
4418 statistical processes (programs). i<acronym>ESS[SAS]</acronym><!-- /@w --> is what is needed for
4419 interactive <acronym>SAS</acronym><!-- /@w --> programming. i<acronym>ESS[SAS]</acronym><!-- /@w --> works best
4425 required to make the redirection of stdio work
4427 keeps output lines from folding on standard terminals
4429 prevents error messages from printing 3 times
4431 permits recovery after syntax errors
4432 </pre>
4435 </pre>
4436 <p>The <samp><span class="file">*SAS:1.log*</span></samp> buffer in <code>ESStr</code> mode corresponds to the file
4437 <samp><var>foo</var><span class="file">.log</span></samp> in <acronym>SAS</acronym><!-- /@w --> batch usage and to the `<samp><span class="samp">SAS: LOG</span></samp>' window in the
4438 <acronym>SAS</acronym><!-- /@w --> Display Manager. All commands submitted to <acronym>SAS</acronym><!-- /@w -->, informative
4439 messages, warnings, and errors appear here.
4441 <p>The <samp><span class="file">*SAS:1.lst*</span></samp> buffer in <code>ESSlst</code> mode corresponds to the file
4442 <samp><var>foo</var><span class="file">.lst</span></samp> in <acronym>SAS</acronym><!-- /@w --> batch usage and to the `<samp><span class="samp">SAS: OUTPUT</span></samp>' window in the
4445 <p>The <samp><span class="file">*SAS:1*</span></samp> buffer exists solely as a communications buffer.
4446 The user should never use this buffer directly.
4447 Files are edited in the <samp><var>foo</var><span class="file">.sas</span></samp> buffer. The <kbd>C-c C-r</kbd><!-- /@w --> key in
4449 `<samp><span class="samp">SAS: PROGRAM EDITOR</span></samp>' window followed by <code>SUBMIT</code>.
4451 <p>For example, open the file you want to work with.
4453 </pre>
4454 <p><samp><var>foo</var><span class="file">.sas</span></samp> will be in <acronym>ESS[SAS]</acronym> mode. Edit as appropriate, and then start
4455 up <acronym>SAS</acronym><!-- /@w --> with the cursor in the <samp><var>foo</var><span class="file">.sas</span></samp> buffer.
4457 </pre>
4458 <p>Four buffers will appear on screen:
4459 <p><table summary=""><tr align="left"><td valign="top">Buffer </td><td valign="top">Mode </td><td valign="top">Description
4460 <br></td></tr><tr align="left"><td valign="top"><samp><var>foo</var><span class="file">.sas</span></samp> </td><td valign="top"><code><acronym>ESS[SAS]</acronym></code> </td><td valign="top">your source file
4461 <br></td></tr><tr align="left"><td valign="top"><samp><span class="file">*SAS:1*</span></samp> </td><td valign="top"><code>i<acronym>ESS[SAS:1]</acronym><!-- /@w --></code> </td><td valign="top">i<acronym>ESS</acronym><!-- /@w --> communication buffer
4462 <br></td></tr><tr align="left"><td valign="top"><samp><span class="file">*SAS:1.log*</span></samp> </td><td valign="top"><code>Shell ESStr []</code> </td><td valign="top"><acronym>SAS</acronym><!-- /@w --> log information
4463 <br></td></tr><tr align="left"><td valign="top"><samp><span class="file">*SAS:1.lst*</span></samp> </td><td valign="top"><code>Shell ESSlst []</code> </td><td valign="top"><acronym>SAS</acronym><!-- /@w --> listing information
4464 <br></td></tr></table>
4465 If you would prefer each of the four buffers to appear in its
4466 own individual frame, you can arrange for that. Place the
4467 cursor in the buffer displaying <samp><var>foo</var><span class="file">.sas</span></samp>. Enter the
4469 <samp><var>foo</var><span class="file">.sas</span></samp>. If not, put it there and <kbd>C-x b </kbd><var>foo</var><kbd>.sas</kbd><!-- /@w -->.
4472 (regions are most useful: a highlighted region will normally
4476 <p>Information appears in the log buffer, analysis results in the
4477 listing buffer. In case of errors, make the corrections in the
4478 <samp><var>foo</var><span class="file">.sas</span></samp> buffer and resubmit with another <kbd>C-c C-r</kbd><!-- /@w -->.
4480 <p>At the end of the session you may save the log and listing
4482 for a file name. Typically, the names <samp><var>foo</var><span class="file">.log</span></samp> and <samp><var>foo</var><span class="file">.lst</span></samp>
4483 will be used. You will almost certainly want to edit the saved
4484 files before including them in a report. The files are
4485 read-only by default. You can make them writable by the emacs
4488 <p>At the end of the session, the input file <samp><var>foo</var><span class="file">.sas</span></samp> will
4489 typically have been revised. You can save it. It can be used
4493 <p>The <samp><span class="file">*SAS:1*</span></samp> buffer is strictly for <acronym>ESS</acronym> use. The user should
4494 never need to read it or write to it. Refer to the <samp><span class="file">.lst</span></samp> and
4497 <p>Troubleshooting: See <a href="#iESS_0028SAS_0029_002d_002dCommon-problems">iESS(SAS)–Common problems</a>.
4499 <!-- node-name, next, previous, up -->
4501 <p><hr>
4504 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dGraphics">ESS(SAS)--Graphics</a>,
4505 Previous: <a rel="previous" accesskey="p" href="#iESS_0028SAS_0029_002d_002dInteractive-SAS-processes">iESS(SAS)--Interactive SAS processes</a>,
4508 </div>
4513 <li>i<acronym>ESS[SAS]</acronym><!-- /@w --> does not work on Windows. In order to run <acronym>SAS</acronym><!-- /@w --> inside
4514 an emacs buffer, it is necessary to start <acronym>SAS</acronym><!-- /@w --> with the <code>-stdio</code> option.
4517 <ul>
4519 <li><samp><span class="file">ess-sas-sh-command</span></samp> (from the <acronym>ESS</acronym> <samp><span class="file">etc</span></samp> directory) needs to be
4521 type <kbd>M-:</kbd>, then at the minibuffer prompt `<samp><span class="samp">Eval:</span></samp>'<!-- /@w -->,
4523 <!-- (solution: @code{chmod ugo+rx ess-sas-sh-command}). -->
4525 <kbd>M-:</kbd> and at the minibuffer prompt `<samp><span class="samp">Eval:</span></samp>', type
4527 </ul>
4528 <li><kbd>M-x SAS</kbd><!-- /@w --> starts <acronym>SAS</acronym><!-- /@w --> Display<!-- /@w --> Manager. Probably, the command <code>sas</code>
4529 on your system calls a shell script. In that case you will need to locate
4533 </pre>
4535 directory, with for example
4537 ln -s /usr/local/sas9/sas sas
4538 </pre>
4539 </ol>
4542 shell script appears.
4544 <!-- Specify the path to the real -->
4545 <!-- @code{sas} executable in @file{ess-sas-sh-command}, i.e.: -->
4546 <!-- @example -->
4547 <!-- /usr/local/sas9/sas $@@ </dev/tty 1>$stdout 2>$stderr -->
4548 <!-- @end example -->
4549 <!-- To find the @code{sas} executable, you can execute the @UNIX{} command: -->
4550 <!-- @example -->
4551 <!-- find / -name sas -print -->
4552 <!-- @end example -->
4553 <!-- @end enumerate -->
4554 <!-- node-name, next, previous, up -->
4556 <p><hr>
4559 Next: <a rel="next" accesskey="n" href="#ESS_0028SAS_0029_002d_002dWindows">ESS(SAS)--Windows</a>,
4560 Previous: <a rel="previous" accesskey="p" href="#iESS_0028SAS_0029_002d_002dCommon-problems">iESS(SAS)--Common problems</a>,
4563 </div>
4567 <p>Output from a <acronym>SAS/GRAPH</acronym><!-- /@w --> <code>PROC</code> can be displayed in a <acronym>SAS/GRAPH</acronym><!-- /@w -->
4568 window for <acronym>SAS</acronym><!-- /@w --> batch on Windows or for both <acronym>SAS</acronym><!-- /@w --> batch and interactive
4571 <samp><var>foo</var><span class="file">.sas</span></samp> or in <samp><span class="file">~/autoexec.sas</span></samp>):
4573 goptions device=ps gsfname=gsasfile gsfmode=append;
4574 </pre>
4576 wish to control the vertical spacing to allow the entire plot
4577 to be visible on screen, for example:
4579 plot a*b / vpos=25;
4580 run;
4581 </pre>
4582 <!-- node-name, next, previous, up -->
4584 <p><hr>
4587 Previous: <a rel="previous" accesskey="p" href="#ESS_0028SAS_0029_002d_002dGraphics">ESS(SAS)--Graphics</a>,
4590 </div>
4594 <ul>
4595 <li>i<acronym>ESS[SAS]</acronym><!-- /@w --> does not work on Windows. See <a href="#iESS_0028SAS_0029_002d_002dCommon-problems">iESS(SAS)–Common problems</a>.
4597 <li><acronym>ESS[SAS]</acronym> mode for editing <acronym>SAS</acronym><!-- /@w --> language files works very well.
4601 You can use batch. See <a href="#ESS_0028SAS_0029_002d_002dBatch-SAS-processes">ESS(SAS)–Batch SAS processes</a>.
4603 <p>Or you can mark regions with the mouse and submit the code with
4606 </ul>
4608 <!-- Local Variables: -->
4609 <!-- TeX-master: "ess.texi" -->
4610 <!-- End: -->
4611 <!-- node-name, next, previous, up -->
4613 <p><hr>
4619 </div>
4625 <li><a accesskey="2" href="#ESS_0028BUGS_0029_002d_002dCommand-files">ESS(BUGS)--Command files</a>
4627 </ul>
4630 was developed by Rodney A. Sparapani and has some similarities with
4633 documentation says BUGS, you can assume that it applies to JAGS as
4635 allow for proper fontification of statements, distributions,
4636 functions, commands and comments in BUGS model files, command files
4638 from the model file so that a BUGS batch process can be defined by a
4639 single file. Third, <acronym>ESS</acronym> provides a BUGS batch script that allows <acronym>ESS</acronym>
4640 to set BUGS batch parameters. Fourth, key sequences are defined to
4641 create a command file and submit a BUGS batch process. Lastly,
4642 interactive submission of BUGS commands is also supported.
4644 <!-- node-name, next, previous, up -->
4646 <p><hr>
4649 Next: <a rel="next" accesskey="n" href="#ESS_0028BUGS_0029_002d_002dCommand-files">ESS(BUGS)--Command files</a>,
4653 </div>
4657 <p>Model files with the <samp><span class="file">.bug</span></samp> extension are edited in <acronym>ESS[BUGS]</acronym> mode
4658 if <code>(require 'essd-bugs)</code> was performed or edited in <acronym>ESS[JAGS]</acronym> mode
4660 Two keys are bound for your use in <acronym>ESS[BUGS]</acronym>, <kbd>F2</kbd> and <kbd>C-c C-c</kbd>.
4662 See <a href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">ESS(SAS)–Function keys for batch processing</a>. <kbd>C-c C-c</kbd> performs the
4664 in an empty buffer for a model file will produce a template for you.
4668 in an empty buffer. They are named by all capitals and start
4669 with <code>%</code>: <code>%N</code>, <code>%DATA</code>, <code>%INIT</code>, <code>%MONITOR</code> and <code>%STATS</code>. When you are
4671 the necessary replacements and build your command file for you. Note
4673 variables are compatible with the JAGS dialect.
4677 except it will have the <samp><span class="file">.dat</span></samp> extension. If your data file is named
4679 file name and no replacement will occur.
4683 replaced by the model file name except it will have the .in extension.
4684 If your model will be generating it's own initial values, place a
4687 appropriate file name.
4690 Although it is commented, it is still active. Notice that later on in
4698 is commented, it is still active. This line is a list of variables
4700 appropriate statements are created in the command file to monitor the
4701 list of variables. If the line is blank, then the list is populated
4705 It is a list of variables for which summary statistics will be
4707 will be generated in your command file.
4714 <!-- node-name, next, previous, up -->
4716 <p><hr>
4719 Next: <a rel="next" accesskey="n" href="#ESS_0028BUGS_0029_002d_002dLog-files">ESS(BUGS)--Log files</a>,
4720 Previous: <a rel="previous" accesskey="p" href="#ESS_0028BUGS_0029_002d_002dModel-files">ESS(BUGS)--Model files</a>,
4723 </div>
4727 <p>To avoid extension name collision, <samp><span class="file">.bmd</span></samp> is used for BUGS
4728 command files and <samp><span class="file">.jmd</span></samp> for JAGS command files. When you have
4730 file is created if one does not already exist. However, the command
4731 file was created, it recognizes two "replacement" variables:
4735 Although they are commented, they are still active. Between them
4736 appears the necessary statements to monitor the list of variables
4738 variable is similar.
4741 again will submit your command file as a batch job. BUGS batch
4744 <samp><span class="file">backbugs</span></samp> for BUGS major version 0.6 and <samp><span class="file">backbug5</span></samp> for
4745 0.5. The DOS script is <samp><span class="file">BACKBUGS.BAT</span></samp> for BUGS major version 0.6
4747 are not readily available with the batch scripts that come with BUGS.
4749 <!-- node-name, next, previous, up -->
4751 <p><hr>
4754 Previous: <a rel="previous" accesskey="p" href="#ESS_0028BUGS_0029_002d_002dCommand-files">ESS(BUGS)--Command files</a>,
4757 </div>
4761 <p>To avoid extension name collision, <samp><span class="file">.bog</span></samp> is used for BUGS log
4763 <samp><span class="file">.bog</span></samp> file from the <samp><span class="file">.log</span></samp> file when the batch process
4764 completes. If you need to look at the <samp><span class="file">.log</span></samp> file while the
4766 You may find <kbd>F2</kbd> useful to refresh the <samp><span class="file">.log</span></samp> if the batch
4767 process over-writes or appends it.
4769 <!-- node-name, next, previous, up -->
4771 <p><hr>
4773 Next: <a rel="next" accesskey="n" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>,
4777 </div>
4781 <p>ESS has a few miscellaneous features, which didn't fit anywhere else.
4791 </ul>
4793 <!-- node-name, next, previous, up -->
4795 <p><hr>
4801 </div>
4805 <p>ESS provides Font-Lock (see <a href="emacs.html#Faces">Using Multiple Typefaces</a>) patterns for Inferior S Mode, S
4806 Mode, and S Transcript Mode buffers.
4808 Syntax highlighting within ESS buffers is controlled by the variable
4810 Input to inferior ESS processes is also highlighted syntactically if
4812 If you change the value of either of these varibles, you need to restart
4813 emacs for your changes to take effect.
4815 <!-- To activate highlighting, you need to turn on Font Lock mode in the -->
4816 <!-- appropriate buffers. This can be done on a per-buffer basis with -->
4817 <!-- @kbd{M-x font-lock-mode}, or may be done by adding -->
4818 <!-- @code{turn-on-font-lock} to @code{inferior-ess-mode-hook}, -->
4819 <!-- @code{ess-mode-hook} and @code{ess-transcript-mode-hook}. Your systems -->
4820 <!-- administrator may have done this for you in @file{ess-site.el} -->
4821 <!-- (@pxref{Customization}). -->
4822 <p>The font-lock patterns are defined in the following variables, which you
4823 may modify if desired:
4826 — Variable: <b>inferior-ess-R-font-lock-keywords</b><var><a name="index-inferior_002dess_002dR_002dfont_002dlock_002dkeywords-196"></a></var><br>
4827 <blockquote><p>Font-lock patterns for inferior *R* processes. (There is a
4829 processes.) The default value highlights prompts, inputs, assignments,
4830 output messages, vector and matrix labels, and literals such as
4832 </p></blockquote></div>
4835 — Variable: <b>ess-R-mode-font-lock-keywords</b><var><a name="index-ess_002dR_002dmode_002dfont_002dlock_002dkeywords-197"></a></var><br>
4836 <blockquote><p>Font-lock patterns for ESS R programming mode. (There is a
4838 default value highlights function names, literals, assignments, source
4839 functions and reserved words.
4840 </p></blockquote></div>
4842 <!-- 2007-11-08 - this var no longer exists. -->
4843 <!-- @defvar ess-trans-font-lock-keywords -->
4844 <!-- Font-lock patterns for ESS Transcript Mode. The default value -->
4845 <!-- highlights the same patterns as in Inferior ESS Mode. -->
4846 <!-- @end defvar -->
4847 <!-- node-name, next, previous, up -->
4849 <p><hr>
4855 </div>
4859 <p>Emacs and XEmacs have facilities for highlighting the parenthesis
4860 matching the parenthesis at point. This feature is very useful when
4861 trying to examine which parentheses match each other. This highlighting
4862 also indicates when parentheses are not matching. Depending on what
4863 version of emacs you use, one of the following should work in your
4864 initialisation file:
4867 (show-paren-mode t) ;for Emacs
4868 </pre>
4869 <!-- node-name, next, previous, up -->
4871 <p><hr>
4877 </div>
4881 <p><a name="index-graphics-198"></a>One of the main features of the <code>S</code> package is its ability to
4882 generate high-resolution graphics plots, and ESS provides a number of
4883 features for dealing with such plots.
4889 </ul>
4891 <!-- node-name, next, previous, up -->
4893 <p><hr>
4899 </div>
4903 <p>This is the simplest (and least desirable) method of using graphics
4905 based plots which can be contained within the ESS process buffer
4906 itself. To start using character graphics, issue the S command
4908 </pre>
4909 <p><a name="index-printer_0028_0029-199"></a>(the <code>width=79</code> argument prevents Emacs line-wrapping at column
4911 a different number of columns.) Plotting commands do not generate
4913 is issued, which displays the current figure.
4915 <!-- node-name, next, previous, up -->
4917 <p><hr>
4923 </div>
4927 <p><a name="index-X-windows-200"></a>Of course, the ideal way to use graphics with ESS is to use a windowing
4928 system. Under X11, this requires that the DISPLAY environment
4929 variable be appropriately set, which may not always be the case within
4930 your Emacs process. ESS provides a facility for setting the value of
4931 DISPLAY before the ESS process is started if the variable
4935 <!-- node-name, next, previous, up -->
4937 <p><hr>
4942 </div>
4947 S+6.1 and newer on Windows contains a java library that supports graphics. Send
4948 the commands:
4951 java.graph()
4952 </pre>
4954 interaction and graphics within S-PLUS. (Thanks to Tim Hesterberg for
4955 this information.)
4957 <!-- node-name, next, previous, up -->
4959 <p><hr>
4965 </div>
4969 <p>Imenu is an Emacs tool for providing mode-specific buffer indexes. In
4970 some of the ESS editing modes (currently SAS and S), support for Imenu
4971 is provided. For example, in S mode buffers, the menubar should display
4972 an item called "Imenu-S". Within this menubar you will then be offered
4973 bookmarks to particular parts of your source file (such as the starting
4974 point of each function definition).
4976 <p>Imenu works by searching your buffer for lines that match what ESS
4977 thinks is the beginning of a suitable entry, e.g. the beginning of a
4978 function definition. To examine the regular expression that ESS uses,
4982 <!-- node-name, next, previous, up -->
4984 <p><hr>
4990 </div>
4994 <p>The R and S editing modes have support for a toolbar. This toolbar
4995 provides icons to act as shortcuts for starting new S/R processes, or
4996 for evaluating regions of your source buffers. The toolbar should be
4997 present if your emacs can display images. See <a href="#Customization">Customization</a>, for ways
4998 to change the toolbar.
5000 <!-- node-name, next, previous, up -->
5002 <p><hr>
5008 </div>
5012 <p>The Emacs tags facility can be used to navigate around your files
5013 containing definitions of S functions. This facility is independent of
5014 ESS usage, but is written here since ESS users may wish to take
5015 advantage of TAGS facility. Read more about emacs tags in an emacs
5016 manual.
5018 <p>Etags, the program that generates the TAGS file, does not yet know the
5019 syntax to recognise function definitions in S files. Hence, you will
5020 need to provide a regexp that matches your function definitions. Here
5021 is an example call (broken over two lines; type as one line) that should
5022 be appropriate.
5026 </pre>
5027 <p>This will find entries in your source file of the form:
5030 </pre>
5032 change the single quotes to double quotes.
5034 <!-- node-name, next, previous, up -->
5036 <p><hr>
5041 </div>
5045 <p>Ess-rdired provides a dired-like buffer for viewing, editing and
5046 plotting objects in your current R session. If you are used to using
5047 the dired (directory editor) facility in Emacs, this mode gives you
5048 similar functionality for R objects.
5050 <p>To get started, first make sure you can load ess-rdired. Add the
5051 following to your .emacs and then restart emacs.
5053 "View *R* objects in a dired-like buffer." t)
5054 </pre>
5056 variables, such as:
5061 z <- TRUE
5062 </pre>
5064 objects in your current environment and display it in a new window:
5066 s numeric 100
5067 x numeric 3
5068 y numeric 20
5069 z logical 1
5070 </pre>
5072 mode. For example, with your point on the line of a variable, `p' will
5073 plot the object, `v' will view it, and `d' will mark the object for
5074 deletion (`x' will actually perform the deletion).
5076 <!-- node-name, next, previous, up@chapter Using S4 -->
5078 <p><hr>
5085 </div>
5094 </ul>
5097 <p><hr>
5100 Previous: <a rel="previous" accesskey="p" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>,
5101 Up: <a rel="up" accesskey="u" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>
5103 </div>
5109 <ul>
5111 cannot be used while the user is entering a multi-line command. The
5112 only real fix in this situation is to use another ESS process.
5115 buffer in the wrong place when point is at the same position as the last
5116 process output. This proves difficult to fix, in general, as we need to
5119 <li>It's possible to clear the modification flag (say, by saving the buffer)
5120 with the edit buffer not having been loaded into S.
5122 <li>Backup files can sometimes be left behind, even when
5126 to hang.
5128 <li>The function-based commands don't always work as expected on functions
5129 whose body is not a parenthesized or compound expression, and don't even
5130 recognize anonymous functions (i.e. functions not assigned to any
5131 variable).
5133 <li>Multi-line commands could be handled better by the command history
5134 mechanism.
5136 <li>Changes to the continutation prompt in R (e.g.
5138 Hence, for now, the best thing is not to change the continuation prompt.
5139 If you do change the continuation prompt, you will need to change
5143 </ul>
5145 <!-- node-name, next, previous, up -->
5147 <p><hr>
5151 Up: <a rel="up" accesskey="u" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>
5153 </div>
5157 <p><a name="index-Bug-reports-204"></a><a name="index-ess_002dsubmit_002dbug_002dreport-205"></a>
5159 <p>Please send bug reports, suggestions etc. to
5162 <p>The easiest way to do this is within Emacs by typing
5166 <p>This also gives the maintainers valuable information about your
5167 installation which may help us to identify or even fix the bug.
5169 <p>If Emacs reports an error, backtraces can help us debug the problem.
5170 Type "M-x set-variable RET debug-on-error RET t RET". Then run the
5171 command that causes the error and you should see a *Backtrace* buffer
5172 containing debug information; send us that buffer.
5174 <p>Note that comments, suggestions, words of praise and large cash
5175 donations are also more than welcome.
5177 <!-- node-name, next, previous, up -->
5179 <p><hr>
5183 Up: <a rel="up" accesskey="u" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>
5185 </div>
5189 <p>There is a mailing list for discussions and announcements relating to
5190 ESS. Join the list by sending an e-mail with "subscribe ess-help" (or
5191 "help") in the body to <a href="mailto:ess-help-request@stat.math.ethz.ch">ess-help-request@stat.math.ethz.ch</a>;
5192 contributions to the list may be mailed to
5193 <a href="mailto:ess-help@stat.math.ethz.ch">ess-help@stat.math.ethz.ch</a>. Rest assured, this is a fairly
5194 low-volume mailing list.
5196 <p>The purposes of the mailing list include
5198 <ul>
5199 <li> helping users of ESS to get along with it.
5200 <li> discussing aspects of using ESS on Emacs and XEmacs.
5201 <li> suggestions for improvements.
5202 <li> announcements of new releases of ESS.
5203 <li> posting small patches to ESS.
5204 </ul>
5206 <!-- node-name, next, previous, up -->
5208 <p><hr>
5211 Up: <a rel="up" accesskey="u" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>
5213 </div>
5217 <p>Emacs is a complex editor with many abilities that we do not have space
5218 to describe here. If you have problems with other features of emacs
5219 (e.g. printing), there are several sources to consult, including the
5221 and EmacsWiki (<a href="http://www.emacswiki.org">http://www.emacswiki.org</a>). Please consult them
5222 before asking on the mailing list about issues that are not specific to
5223 ESS.
5225 <!-- _not_yet_ @node Help OS, Installation, Help for Statistical Packages, Top -->
5226 <!-- _not_yet_ @comment node-name, next, previous, up -->
5227 <!-- _not_yet_ @chapter Help, arranged by Operating System -->
5228 <!-- _not_yet_ -->
5229 <!-- _not_yet_ @menu -->
5230 <!-- _not_yet_ * Unix installation:: -->
5231 <!-- _not_yet_ * Microsoft Windows installation:: -->
5232 <!-- _not_yet_ * System dependent:: Other variables you may need to change -->
5233 <!-- _not_yet_ @end menu -->
5234 <!-- node-name, next, previous, up -->
5236 <p><hr>
5239 Previous: <a rel="previous" accesskey="p" href="#Mailing-lists_002fbug-reports">Mailing lists/bug reports</a>,
5242 </div>
5247 ESS can be easily customized to your taste simply by including the
5248 appropriate lines in your <samp><span class="file">.emacs</span></samp> file. There are numerous
5249 variables which affect the behavior of ESS in certain situations which
5250 can be modified to your liking. Keybindings may be set or changed to
5251 your preferences, and for per-buffer customizations hooks are also
5252 available.
5254 <p>Most of these variables can be viewed and set using the Custom facility
5256 ESS variables that can be customized. Variables are grouped by subject
5257 to make it easy to find related variables.
5259 <!-- Stephen deleted incomplete variable list Wed 25 Aug 2004. -->
5261 <p><hr>
5267 </div>
5273 <!-- @unnumbered Command and Function Index -->
5274 <!-- @printindex fn -->
5275 <!-- node-name, next, previous, up -->
5277 <p><hr>
5279 Next: <a rel="next" accesskey="n" href="#Variable-and-command-index">Variable and command index</a>,
5283 </div>
5290 <li><a href="#index-g_t_0040file_007b_002eemacs_007d-file-175"><samp><span class="file">.emacs</span></samp> file</a>: <a href="#Source-Directories">Source Directories</a></li>
5291 <li><a href="#index-g_t_0040file_007b_002eemacs_007d-file-158"><samp><span class="file">.emacs</span></samp> file</a>: <a href="#Indenting">Indenting</a></li>
5292 <li><a href="#index-aborting-S-commands-110">aborting S commands</a>: <a href="#Other">Other</a></li>
5293 <li><a href="#index-aborting-the-ESS-process-115">aborting the ESS process</a>: <a href="#Other">Other</a></li>
5294 <li><a href="#index-arguments-to-S-program-30">arguments to S program</a>: <a href="#Customizing-startup">Customizing startup</a></li>
5296 <li><a href="#index-autosaving-170">autosaving</a>: <a href="#Source-Files">Source Files</a></li>
5297 <li><a href="#index-Bug-reports-204">Bug reports</a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li>
5301 <li><a href="#index-command-history-71">command history</a>: <a href="#Command-History">Command History</a></li>
5302 <li><a href="#index-command_002dline-completion-40">command-line completion</a>: <a href="#Completion">Completion</a></li>
5303 <li><a href="#index-command_002dline-editing-34">command-line editing</a>: <a href="#Command_002dline-editing">Command-line editing</a></li>
5304 <li><a href="#index-commands-32">commands</a>: <a href="#Entering-commands">Entering commands</a></li>
5306 <li><a href="#index-comments-in-S-153">comments in S</a>: <a href="#Indenting">Indenting</a></li>
5307 <li><a href="#index-completion-in-edit-buffer-161">completion in edit buffer</a>: <a href="#Other-edit-buffer-commands">Other edit buffer commands</a></li>
5308 <li><a href="#index-completion-of-object-names-39">completion of object names</a>: <a href="#Completion">Completion</a></li>
5309 <li><a href="#index-completion-on-file-names-48">completion on file names</a>: <a href="#Completion">Completion</a></li>
5310 <li><a href="#index-completion-on-lists-47">completion on lists</a>: <a href="#Completion">Completion</a></li>
5311 <li><a href="#index-completion_002c-when-prompted-for-object-names-124">completion, when prompted for object names</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5312 <li><a href="#index-creating-new-objects-125">creating new objects</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5314 <li><a href="#index-customization-206">customization</a>: <a href="#Customization">Customization</a></li>
5316 <li><a href="#index-debugging-S-functions-151">debugging S functions</a>: <a href="#Evaluating-code">Evaluating code</a></li>
5317 <li><a href="#index-deleting-output-58">deleting output</a>: <a href="#Last-command">Last command</a></li>
5318 <li><a href="#index-directories-16">directories</a>: <a href="#Starting-up">Starting up</a></li>
5319 <li><a href="#index-dump-file-directories-173">dump file directories</a>: <a href="#Source-Directories">Source Directories</a></li>
5320 <li><a href="#index-dump-file-names-171">dump file names</a>: <a href="#Source-Directories">Source Directories</a></li>
5321 <li><a href="#index-dump-files-164">dump files</a>: <a href="#Source-Files">Source Files</a></li>
5322 <li><a href="#index-dump-files-128">dump files</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5323 <li><a href="#index-echoing-commands-when-evaluating-138">echoing commands when evaluating</a>: <a href="#Evaluating-code">Evaluating code</a></li>
5324 <li><a href="#index-edit-buffer-122">edit buffer</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5325 <li><a href="#index-editing-commands-72">editing commands</a>: <a href="#Command-History">Command History</a></li>
5326 <li><a href="#index-editing-functions-121">editing functions</a>: <a href="#Editing">Editing</a></li>
5327 <li><a href="#index-editing-transcripts-69">editing transcripts</a>: <a href="#Saving-transcripts">Saving transcripts</a></li>
5328 <li><a href="#index-emacsclient-108">emacsclient</a>: <a href="#Emacsclient">Emacsclient</a></li>
5329 <li><a href="#index-entering-commands-31">entering commands</a>: <a href="#Entering-commands">Entering commands</a></li>
5331 <li><a href="#index-ESS-process-buffer-17">ESS process buffer</a>: <a href="#Starting-up">Starting up</a></li>
5332 <li><a href="#index-ESS-process-directory-13">ESS process directory</a>: <a href="#Starting-up">Starting up</a></li>
5333 <li><a href="#index-evaluating-code-with-echoed-commands-139">evaluating code with echoed commands</a>: <a href="#Evaluating-code">Evaluating code</a></li>
5334 <li><a href="#index-evaluating-S-expressions-140">evaluating S expressions</a>: <a href="#Evaluating-code">Evaluating code</a></li>
5335 <li><a href="#index-Font_002dlock-mode-194">Font-lock mode</a>: <a href="#Highlighting">Highlighting</a></li>
5336 <li><a href="#index-formatting-source-code-157">formatting source code</a>: <a href="#Indenting">Indenting</a></li>
5339 <li><a href="#index-highlighting-195">highlighting</a>: <a href="#Highlighting">Highlighting</a></li>
5340 <li><a href="#index-historic-backups-169">historic backups</a>: <a href="#Source-Files">Source Files</a></li>
5343 <li><a href="#index-installation-9">installation</a>: <a href="#Installation">Installation</a></li>
5344 <li><a href="#index-interactive-use-of-S-2">interactive use of S</a>: <a href="#Introduction">Introduction</a></li>
5345 <li><a href="#index-interrupting-S-commands-111">interrupting S commands</a>: <a href="#Other">Other</a></li>
5346 <li><a href="#index-introduction-1">introduction</a>: <a href="#Introduction">Introduction</a></li>
5347 <li><a href="#index-keyboard-short-cuts-93">keyboard short cuts</a>: <a href="#Hot-keys">Hot keys</a></li>
5348 <li><a href="#index-killing-temporary-buffers-105">killing temporary buffers</a>: <a href="#Hot-keys">Hot keys</a></li>
5349 <li><a href="#index-killing-the-ESS-process-99">killing the ESS process</a>: <a href="#Hot-keys">Hot keys</a></li>
5350 <li><a href="#index-lists_002c-completion-on-46">lists, completion on</a>: <a href="#Completion">Completion</a></li>
5351 <li><a href="#index-motion-in-transcript-mode-118">motion in transcript mode</a>: <a href="#Transcript-Mode">Transcript Mode</a></li>
5352 <li><a href="#index-multi_002dline-commands_002c-resubmitting-66">multi-line commands, resubmitting</a>: <a href="#Transcript-resubmit">Transcript resubmit</a></li>
5353 <li><a href="#index-Multiple-ESS-processes-19">Multiple ESS processes</a>: <a href="#Multiple-ESS-processes">Multiple ESS processes</a></li>
5354 <li><a href="#index-new-objects_002c-creating-126">new objects, creating</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5356 <li><a href="#index-pages-in-the-process-buffer-53">pages in the process buffer</a>: <a href="#Transcript">Transcript</a></li>
5357 <li><a href="#index-paging-commands-in-help-buffers-184">paging commands in help buffers</a>: <a href="#Help">Help</a></li>
5358 <li><a href="#index-paragraphs-in-the-process-buffer-52">paragraphs in the process buffer</a>: <a href="#Transcript">Transcript</a></li>
5359 <li><a href="#index-parsing-errors-134">parsing errors</a>: <a href="#Error-Checking">Error Checking</a></li>
5360 <li><a href="#index-process-buffer-18">process buffer</a>: <a href="#Starting-up">Starting up</a></li>
5361 <li><a href="#index-process-names-20">process names</a>: <a href="#Multiple-ESS-processes">Multiple ESS processes</a></li>
5362 <li><a href="#index-programming-in-S-5">programming in S</a>: <a href="#Introduction">Introduction</a></li>
5363 <li><a href="#index-project-work-in-S-168">project work in S</a>: <a href="#Source-Files">Source Files</a></li>
5364 <li><a href="#index-quitting-from-ESS-98">quitting from ESS</a>: <a href="#Hot-keys">Hot keys</a></li>
5365 <li><a href="#index-re_002dexecuting-commands-73">re-executing commands</a>: <a href="#Command-History">Command History</a></li>
5366 <li><a href="#index-reading-long-command-outputs-55">reading long command outputs</a>: <a href="#Last-command">Last command</a></li>
5367 <li><a href="#index-Remote-Computers-22">Remote Computers</a>: <a href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a></li>
5368 <li><a href="#index-reverting-function-definitions-129">reverting function definitions</a>: <a href="#Edit-buffer">Edit buffer</a></li>
5370 <li><a href="#index-search-list-177">search list</a>: <a href="#Source-Directories">Source Directories</a></li>
5372 <li><a href="#index-sending-input-33">sending input</a>: <a href="#Entering-commands">Entering commands</a></li>
5373 <li><a href="#index-starting-directory-14">starting directory</a>: <a href="#Starting-up">Starting up</a></li>
5374 <li><a href="#index-starting-ESS-10">starting ESS</a>: <a href="#Starting-up">Starting up</a></li>
5375 <li><a href="#index-stepping-through-code-150">stepping through code</a>: <a href="#Evaluating-code">Evaluating code</a></li>
5376 <li><a href="#index-STERM-106">STERM</a>: <a href="#Statistical-Process-running-in-ESS_003f">Statistical Process running in ESS?</a></li>
5378 <li><a href="#index-temporary-buffers-193">temporary buffers</a>: <a href="#Help">Help</a></li>
5379 <li><a href="#index-temporary-buffers_002c-killing-104">temporary buffers, killing</a>: <a href="#Hot-keys">Hot keys</a></li>
5381 <li><a href="#index-transcript-file-28">transcript file</a>: <a href="#Customizing-startup">Customizing startup</a></li>
5382 <li><a href="#index-transcript-file-names-68">transcript file names</a>: <a href="#Saving-transcripts">Saving transcripts</a></li>
5383 <li><a href="#index-transcript-mode-motion-117">transcript mode motion</a>: <a href="#Transcript-Mode">Transcript Mode</a></li>
5384 <li><a href="#index-transcripts-of-S-sessions-4">transcripts of S sessions</a>: <a href="#Introduction">Introduction</a></li>
5385 <li><a href="#index-using-S-interactively-3">using S interactively</a>: <a href="#Introduction">Introduction</a></li>
5387 <li><a href="#index-working-directory-178">working directory</a>: <a href="#Source-Directories">Source Directories</a></li>
5388 <li><a href="#index-working-directory-15">working directory</a>: <a href="#Starting-up">Starting up</a></li>
5391 <p><hr>
5396 </div>
5403 <li><a href="#index-attach_0028_0029-95"><code>attach()</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5404 <li><a href="#index-backward_002dkill_002dword-36"><code>backward-kill-word</code></a>: <a href="#Command_002dline-editing">Command-line editing</a></li>
5405 <li><a href="#index-comint_002dbackward_002dmatching_002dinput-61"><code>comint-backward-matching-input</code></a>: <a href="#Process-buffer-motion">Process buffer motion</a></li>
5406 <li><a href="#index-comint_002dbol-38"><code>comint-bol</code></a>: <a href="#Command_002dline-editing">Command-line editing</a></li>
5407 <li><a href="#index-comint_002dcopy_002dold_002dinput-64"><code>comint-copy-old-input</code></a>: <a href="#Transcript-resubmit">Transcript resubmit</a></li>
5408 <li><a href="#index-comint_002ddelimiter_002dargument_002dlist-81"><code>comint-delimiter-argument-list</code></a>: <a href="#History-expansion">History expansion</a></li>
5409 <li><a href="#index-comint_002ddynamic_002dcomplete-41"><code>comint-dynamic-complete</code></a>: <a href="#Completion">Completion</a></li>
5410 <li><a href="#index-comint_002dforward_002dmatching_002dinput-62"><code>comint-forward-matching-input</code></a>: <a href="#Process-buffer-motion">Process buffer motion</a></li>
5411 <li><a href="#index-comint_002dinput_002dring_002dsize-74"><code>comint-input-ring-size</code></a>: <a href="#Command-History">Command History</a></li>
5412 <li><a href="#index-comint_002dinterrupt_002dsubjob-109"><code>comint-interrupt-subjob</code></a>: <a href="#Other">Other</a></li>
5413 <li><a href="#index-comint_002dkill_002dinput-37"><code>comint-kill-input</code></a>: <a href="#Command_002dline-editing">Command-line editing</a></li>
5414 <li><a href="#index-comint_002dkill_002doutput-57"><code>comint-kill-output</code></a>: <a href="#Last-command">Last command</a></li>
5415 <li><a href="#index-comint_002dnext_002dinput-76"><code>comint-next-input</code></a>: <a href="#Command-History">Command History</a></li>
5416 <li><a href="#index-comint_002dnext_002dinput-60"><code>comint-next-input</code></a>: <a href="#Process-buffer-motion">Process buffer motion</a></li>
5417 <li><a href="#index-comint_002dnext_002dmatching_002dinput-78"><code>comint-next-matching-input</code></a>: <a href="#Command-History">Command History</a></li>
5418 <li><a href="#index-comint_002dnext_002dmatching_002dinput_002dfrom_002dinput-80"><code>comint-next-matching-input-from-input</code></a>: <a href="#Command-History">Command History</a></li>
5419 <li><a href="#index-comint_002dprevious_002dinput-75"><code>comint-previous-input</code></a>: <a href="#Command-History">Command History</a></li>
5420 <li><a href="#index-comint_002dprevious_002dinput-59"><code>comint-previous-input</code></a>: <a href="#Process-buffer-motion">Process buffer motion</a></li>
5421 <li><a href="#index-comint_002dprevious_002dmatching_002dinput-77"><code>comint-previous-matching-input</code></a>: <a href="#Command-History">Command History</a></li>
5422 <li><a href="#index-comint_002dprevious_002dmatching_002dinput_002dfrom_002dinput-79"><code>comint-previous-matching-input-from-input</code></a>: <a href="#Command-History">Command History</a></li>
5423 <li><a href="#index-comint_002dshow_002dmaximum_002doutput-54"><code>comint-show-maximum-output</code></a>: <a href="#Last-command">Last command</a></li>
5424 <li><a href="#index-comint_002dshow_002doutput-56"><code>comint-show-output</code></a>: <a href="#Last-command">Last command</a></li>
5425 <li><a href="#index-comint_002dstop_002dsubjob-113"><code>comint-stop-subjob</code></a>: <a href="#Other">Other</a></li>
5426 <li><a href="#index-comment_002dcolumn-154"><code>comment-column</code></a>: <a href="#Indenting">Indenting</a></li>
5427 <li><a href="#index-dump_0028_0029-130"><code>dump()</code></a>: <a href="#Edit-buffer">Edit buffer</a></li>
5428 <li><a href="#index-ess_002dabort-112"><code>ess-abort</code></a>: <a href="#Other">Other</a></li>
5429 <li><a href="#index-ess_002dask_002dabout_002ddisplay-201"><code>ess-ask-about-display</code></a>: <a href="#X11">X11</a></li>
5430 <li><a href="#index-ess_002dask_002dabout_002dtransfile-67"><code>ess-ask-about-transfile</code></a>: <a href="#Saving-transcripts">Saving transcripts</a></li>
5431 <li><a href="#index-ess_002dask_002dabout_002dtransfile-27"><code>ess-ask-about-transfile</code></a>: <a href="#Customizing-startup">Customizing startup</a></li>
5432 <li><a href="#index-ess_002dask_002dfor_002dess_002ddirectory-26"><code>ess-ask-for-ess-directory</code></a>: <a href="#Customizing-startup">Customizing startup</a></li>
5433 <li><a href="#index-ess_002dbeginning_002dof_002dfunction-159"><code>ess-beginning-of-function</code></a>: <a href="#Other-edit-buffer-commands">Other edit buffer commands</a></li>
5434 <li><a href="#index-ess_002dchange_002dsp_002dregexp-49"><code>ess-change-sp-regexp</code></a>: <a href="#Completion-details">Completion details</a></li>
5435 <li><a href="#index-ess_002dcleanup-192"><code>ess-cleanup</code></a>: <a href="#Help">Help</a></li>
5436 <li><a href="#index-ess_002dcleanup-102"><code>ess-cleanup</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5437 <li><a href="#index-ess_002ddelete_002ddump_002dfiles-165"><code>ess-delete-dump-files</code></a>: <a href="#Source-Files">Source Files</a></li>
5438 <li><a href="#index-ess_002ddescribe_002dhelp_002dmode-182"><code>ess-describe-help-mode</code></a>: <a href="#Help">Help</a></li>
5439 <li><a href="#index-ess_002ddirectory-176"><code>ess-directory</code></a>: <a href="#Source-Directories">Source Directories</a></li>
5440 <li><a href="#index-ess_002ddisplay_002dhelp_002don_002dobject-181"><code>ess-display-help-on-object</code></a>: <a href="#Help">Help</a></li>
5441 <li><a href="#index-ess_002ddump_002dfilename_002dtemplate-172"><code>ess-dump-filename-template</code></a>: <a href="#Source-Directories">Source Directories</a></li>
5442 <li><a href="#index-ess_002ddump_002dobject_002dinto_002dedit_002dbuffer-123"><code>ess-dump-object-into-edit-buffer</code></a>: <a href="#Edit-buffer">Edit buffer</a></li>
5443 <li><a href="#index-ess_002ddump_002dobject_002dinto_002dedit_002dbuffer-116"><code>ess-dump-object-into-edit-buffer</code></a>: <a href="#Other">Other</a></li>
5444 <li><a href="#index-ESS_002delsewhere-24"><code>ESS-elsewhere</code></a>: <a href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a></li>
5445 <li><a href="#index-ess_002dend_002dof_002dfunction-160"><code>ess-end-of-function</code></a>: <a href="#Other-edit-buffer-commands">Other edit buffer commands</a></li>
5446 <li><a href="#index-ess_002deval_002dbuffer-147"><code>ess-eval-buffer</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5447 <li><a href="#index-ess_002deval_002dfunction-143"><code>ess-eval-function</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5448 <li><a href="#index-ess_002deval_002dfunction_002dand_002dgo-144"><code>ess-eval-function-and-go</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5449 <li><a href="#index-ess_002deval_002dline-141"><code>ess-eval-line</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5450 <li><a href="#index-ess_002deval_002dline_002dand_002dgo-142"><code>ess-eval-line-and-go</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5451 <li><a href="#index-ess_002deval_002dline_002dand_002dstep-188"><code>ess-eval-line-and-step</code></a>: <a href="#Help">Help</a></li>
5452 <li><a href="#index-ess_002deval_002dline_002dand_002dstep-149"><code>ess-eval-line-and-step</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5453 <li><a href="#index-ess_002deval_002dregion-189"><code>ess-eval-region</code></a>: <a href="#Help">Help</a></li>
5454 <li><a href="#index-ess_002deval_002dregion-145"><code>ess-eval-region</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5455 <li><a href="#index-ess_002deval_002dregion_002dand_002dgo-146"><code>ess-eval-region-and-go</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5456 <li><a href="#index-ess_002deval_002dvisibly_002dp-136"><code>ess-eval-visibly-p</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5457 <li><a href="#index-ess_002dexecute-91"><code>ess-execute</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5458 <li><a href="#index-ess_002dexecute_002dattach-94"><code>ess-execute-attach</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5459 <li><a href="#index-ess_002dexecute_002din_002dprocess_002dbuffer-82"><code>ess-execute-in-process-buffer</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5460 <li><a href="#index-ess_002dexecute_002din_002dtb-152"><code>ess-execute-in-tb</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5461 <li><a href="#index-ess_002dexecute_002dobjects-83"><code>ess-execute-objects</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5462 <li><a href="#index-ess_002dexecute_002dsearch-87"><code>ess-execute-search</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5463 <li><a href="#index-ess_002dfancy_002dcomments-155"><code>ess-fancy-comments</code></a>: <a href="#Indenting">Indenting</a></li>
5464 <li><a href="#index-ess_002dfunction_002dtemplate-127"><code>ess-function-template</code></a>: <a href="#Edit-buffer">Edit buffer</a></li>
5465 <li><a href="#index-ess_002dkeep_002ddump_002dfiles-166"><code>ess-keep-dump-files</code></a>: <a href="#Source-Files">Source Files</a></li>
5466 <li><a href="#index-ess_002dlist_002dobject_002dcompletions-45"><code>ess-list-object-completions</code></a>: <a href="#Completion">Completion</a></li>
5467 <li><a href="#index-ess_002dload_002dfile-131"><code>ess-load-file</code></a>: <a href="#Loading">Loading</a></li>
5468 <li><a href="#index-ess_002dload_002dfile-96"><code>ess-load-file</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5469 <li><a href="#index-ess_002dparse_002derrors-135"><code>ess-parse-errors</code></a>: <a href="#Error-Checking">Error Checking</a></li>
5470 <li><a href="#index-ess_002dparse_002derrors-97"><code>ess-parse-errors</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5472 <li><a href="#index-ess_002dquit-114"><code>ess-quit</code></a>: <a href="#Other">Other</a></li>
5473 <li><a href="#index-ess_002dR_002dmode_002dfont_002dlock_002dkeywords-197"><code>ess-R-mode-font-lock-keywords</code></a>: <a href="#Highlighting">Highlighting</a></li>
5474 <li><a href="#index-ess_002dremote-23"><code>ess-remote</code></a>: <a href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a></li>
5475 <li><a href="#index-ess_002drequest_002da_002dprocess-21"><code>ess-request-a-process</code></a>: <a href="#Multiple-ESS-processes">Multiple ESS processes</a></li>
5476 <li><a href="#index-ess_002dresynch-50"><code>ess-resynch</code></a>: <a href="#Completion-details">Completion details</a></li>
5477 <li><a href="#index-ess_002dsearch_002dlist-179"><code>ess-search-list</code></a>: <a href="#Source-Directories">Source Directories</a></li>
5478 <li><a href="#index-ess_002dskip_002dto_002dhelp_002dsection-187"><code>ess-skip-to-help-section</code></a>: <a href="#Help">Help</a></li>
5479 <li><a href="#index-ess_002dskip_002dto_002dnext_002dsection-185"><code>ess-skip-to-next-section</code></a>: <a href="#Help">Help</a></li>
5480 <li><a href="#index-ess_002dskip_002dto_002dprevious_002dsection-186"><code>ess-skip-to-previous-section</code></a>: <a href="#Help">Help</a></li>
5481 <li><a href="#index-ess_002dsource_002ddirectory-174"><code>ess-source-directory</code></a>: <a href="#Source-Directories">Source Directories</a></li>
5482 <li><a href="#index-ess_002dsubmit_002dbug_002dreport-205"><code>ess-submit-bug-report</code></a>: <a href="#Reporting-Bugs">Reporting Bugs</a></li>
5483 <li><a href="#index-ess_002dswitch_002dto_002dend_002dof_002dESS-190"><code>ess-switch-to-end-of-ESS</code></a>: <a href="#Help">Help</a></li>
5484 <li><a href="#index-ess_002dswitch_002dto_002dend_002dof_002dESS-162"><code>ess-switch-to-end-of-ESS</code></a>: <a href="#Other-edit-buffer-commands">Other edit buffer commands</a></li>
5485 <li><a href="#index-ess_002dswitch_002dto_002dESS-163"><code>ess-switch-to-ESS</code></a>: <a href="#Other-edit-buffer-commands">Other edit buffer commands</a></li>
5486 <li><a href="#index-ess_002dtranscript_002dclean_002dregion-70"><code>ess-transcript-clean-region</code></a>: <a href="#Saving-transcripts">Saving transcripts</a></li>
5487 <li><a href="#index-ess_002dtranscript_002dcopy_002dcommand-120"><code>ess-transcript-copy-command</code></a>: <a href="#Resubmit">Resubmit</a></li>
5488 <li><a href="#index-ess_002dtranscript_002dsend_002dcommand-119"><code>ess-transcript-send-command</code></a>: <a href="#Resubmit">Resubmit</a></li>
5489 <li><a href="#index-ess_002dtranscript_002dsend_002dcommand_002dand_002dmove-65"><code>ess-transcript-send-command-and-move</code></a>: <a href="#Transcript-resubmit">Transcript resubmit</a></li>
5490 <li><a href="#index-exit_0028_0029-101"><code>exit()</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5491 <li><a href="#index-inferior_002dess_002dprogram-29"><code>inferior-ess-program</code></a>: <a href="#Customizing-startup">Customizing startup</a></li>
5492 <li><a href="#index-inferior_002dess_002dR_002dfont_002dlock_002dkeywords-196"><code>inferior-ess-R-font-lock-keywords</code></a>: <a href="#Highlighting">Highlighting</a></li>
5493 <li><a href="#index-inferior_002dess_002dsend_002dinput-63"><code>inferior-ess-send-input</code></a>: <a href="#Transcript-resubmit">Transcript resubmit</a></li>
5494 <li><a href="#index-inferior_002dess_002dsend_002dinput-35"><code>inferior-ess-send-input</code></a>: <a href="#Command_002dline-editing">Command-line editing</a></li>
5495 <li><a href="#index-objects_0028_0029-84"><code>objects()</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5496 <li><a href="#index-printer_0028_0029-199"><code>printer()</code></a>: <a href="#printer">printer</a></li>
5497 <li><a href="#index-q_0028_0029-100"><code>q()</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5499 <li><a href="#index-S_002belsewhere-25"><code>S+elsewhere</code></a>: <a href="#ESS-processes-on-Remote-Computers">ESS processes on Remote Computers</a></li>
5500 <li><a href="#index-search_0028_0029-88"><code>search()</code></a>: <a href="#Hot-keys">Hot keys</a></li>
5501 <li><a href="#index-search_0028_0029-43"><code>search()</code></a>: <a href="#Completion">Completion</a></li>
5502 <li><a href="#index-source_0028_0029-137"><code>source()</code></a>: <a href="#Evaluating-code">Evaluating code</a></li>
5503 <li><a href="#index-source_0028_0029-132"><code>source()</code></a>: <a href="#Loading">Loading</a></li>
5504 <li><a href="#index-STERM-107"><code>STERM</code></a>: <a href="#Statistical-Process-running-in-ESS_003f">Statistical Process running in ESS?</a></li>
5505 </ul>
5508 <ul>
5511 <ul>
5517 </li></ul>
5519 <ul>
5523 </li></ul>
5524 <li><a name="toc_Interactive-ESS" href="#Interactive-ESS">3 Interacting with statistical programs</a>
5525 <ul>
5531 </li></ul>
5532 <li><a name="toc_Entering-commands" href="#Entering-commands">4 Interacting with the ESS process</a>
5533 <ul>
5538 <ul>
5543 </li></ul>
5547 <li><a href="#Statistical-Process-running-in-ESS_003f">4.8 Is the Statistical Process running under ESS?</a>
5550 </li></ul>
5551 <li><a name="toc_Transcript-Mode" href="#Transcript-Mode">5 Manipulating saved transcript files</a>
5552 <ul>
5555 </li></ul>
5557 <ul>
5559 <li><a href="#iESS_0028S_0029_002d_002dInferior-ESS-processes">6.2 iESS[S]–Inferior ESS processes</a>
5560 <li><a href="#ESS_002dhelp_002d_002dassistance-with-viewing-help">6.3 ESS-help–assistance with viewing help</a>
5562 <li><a href="#Scenarios-for-use-_0028possibilities_002d_002dbased-on-actual-usage_0029">6.5 Scenarios for use (possibilities–based on actual usage)</a>
5563 <li><a href="#Customization-Examples-and-Solutions-to-Problems">6.6 Customization Examples and Solutions to Problems</a>
5564 </li></ul>
5566 <ul>
5575 </li></ul>
5576 <li><a name="toc_Editing-R-documentation-files" href="#Editing-R-documentation-files">8 Editing R documentation files</a>
5579 <ul>
5580 <li><a href="#ESS_0028SAS_0029_002d_002dDesign-philosophy">10.1 ESS(SAS)–Design philosophy</a>
5583 <li><a href="#ESS_0028SAS_0029_002d_002dBatch-SAS-processes">10.4 ESS(SAS)–Batch SAS processes</a>
5584 <li><a href="#ESS_0028SAS_0029_002d_002dFunction-keys-for-batch-processing">10.5 ESS(SAS)–Function keys for batch processing</a>
5585 <li><a href="#iESS_0028SAS_0029_002d_002dInteractive-SAS-processes">10.6 iESS(SAS)–Interactive SAS processes</a>
5586 <li><a href="#iESS_0028SAS_0029_002d_002dCommon-problems">10.7 iESS(SAS)–Common problems</a>
5589 </li></ul>
5591 <ul>
5595 </li></ul>
5597 <ul>
5601 <ul>
5605 </li></ul>
5610 </li></ul>
5611 <li><a name="toc_Mailing-lists_002fbug-reports" href="#Mailing-lists_002fbug-reports">13 Bugs and Bug Reporting, Mailing Lists</a>
5612 <ul>
5617 </li></ul>
5621 <li><a name="toc_Variable-and-command-index" href="#Variable-and-command-index">Variable and command index</a>
5622 </li></ul>
5623 </div>
5626 <hr>
5627 <a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small>
5628 require the files.el patch to revert-buffer for the Local Variables
5629 updating problem</p>
5631 <p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> The variable <code>ess-change-sp-regexp</code> is a regular
5632 expression matching commands which change the search list. You will
5633 need to modify this variable if you have defined custom commands (other
5634 than <code>attach</code>, <code>detach</code>, <code>collection</code> or <code>library</code>)
5635 which modify the search list.</p>
5637 <p><hr></div>
5639 </body></html>