1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
38 Fortran mode assumes that you follow certain conventions that
39 simplify the task of understanding a Fortran program well enough to
42 * Two nested `do' loops never share a `continue' statement.
44 * The same character appears in column 5 of all continuation lines.
45 It is the value of the variable `fortran-continuation-char'. By
46 default, this character is `$'.
48 If you fail to follow these conventions, the indentation commands may
49 indent some lines unaesthetically. However, a correct Fortran program
50 will retain its meaning when reindented even if the conventions are not
54 File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
56 Variables for Fortran Indentation
57 .................................
59 Several additional variables control how Fortran indentation works.
62 Extra indentation within each level of `do' statement (the default
66 Extra indentation within each level of `if' statement (the default
69 `fortran-continuation-indent'
70 Extra indentation for bodies of continuation lines (the default is
73 `fortran-check-all-num-for-matching-do'
74 If this is `nil', indentation assumes that each `do' statement
75 ends on a `continue' statement. Therefore, when computing
76 indentation for a statement other than `continue', it can save
77 time by not checking for a `do' statement ending there. If this
78 is non-`nil', indenting any numbered statement must check for a
79 `do' that ends there. The default is `nil'.
81 `fortran-minimum-statement-indent'
82 Minimum indentation for Fortran statements. For standard Fortran,
83 this is 6. Statement bodies are always indented at least this
87 File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
92 The usual Emacs comment commands assume that a comment can follow a
93 line of code. In Fortran, the standard comment syntax requires an
94 entire line to be just a comment. Therefore, Fortran mode replaces the
95 standard Emacs comment commands and defines some new variables.
97 Fortran mode can also handle a non-standard comment syntax where
98 comments start with `!' and can follow other text. Because only some
99 Fortran compilers accept this syntax, Fortran mode will not insert such
100 comments unless you have specified to do so in advance by setting the
101 variable `comment-start' to `"!"' (*note Variables::).
104 Align comment or insert new comment (`fortran-comment-indent').
107 Applies to nonstandard `!' comments only.
110 Turn all lines of the region into comments, or (with arg) turn
111 them back into real code (`fortran-comment-region').
113 `M-;' in Fortran mode is redefined as the command
114 `fortran-comment-indent'. Like the usual `M-;' command, it recognizes
115 an existing comment and aligns its text appropriately. If there is no
116 existing comment, a comment is inserted and aligned.
118 Inserting and aligning comments is not the same in Fortran mode as in
119 other modes. When a new comment must be inserted, a full-line comment
120 is inserted if the current line is blank. On a non-blank line, a
121 non-standard `!' comment is inserted if you previously specified you
122 wanted to use them. Otherwise a full-line comment is inserted on a new
123 line before the current line.
125 Non-standard `!' comments are aligned like comments in other
126 languages, but full-line comments are aligned differently. In a
127 standard full-line comment, the comment delimiter itself must always
128 appear in column zero. What can be aligned is the text within the
129 comment. You can choose from three styles of alignment by setting the
130 variable `fortran-comment-indent-style' to one of these values:
133 The text is aligned at a fixed column, which is the value of
134 `fortran-comment-line-column'. This is the default.
137 The text is aligned as if it were a line of code, but with an
138 additional `fortran-comment-line-column' columns of indentation.
141 Text in full-line columns is not moved automatically.
143 You can also specify the character to be used to indent within
144 full-line comments by setting the variable `fortran-comment-indent-char'
145 to the character you want to use.
147 Fortran mode introduces two variables `comment-line-start' and
148 `comment-line-start-skip', which do for full-line comments what
149 `comment-start' and `comment-start-skip' do for ordinary text-following
150 comments. Normally these are set properly by Fortran mode, so you do
151 not need to change them.
153 The normal Emacs comment command `C-x ;' has not been redefined. It
154 can therefore be used if you use `!' comments, but is useless in
155 Fortran mode otherwise.
157 The command `C-c ;' (`fortran-comment-region') turns all the lines
158 of the region into comments by inserting the string `C$$$' at the front
159 of each one. With a numeric arg, the region is turned back into live
160 code by deleting `C$$$' from the front of each line. You can control
161 the string used for the comments by setting the variable
162 `fortran-comment-region'. Note that here we have an example of a
163 command and a variable with the same name; the two uses of the name
164 never conflict because in Lisp and in Emacs it is always clear from the
165 context which one is referred to.
168 File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
174 Displays a "column ruler" momentarily above the current line
175 (`fortran-column-ruler').
178 Splits the current window horizontally so that it is 72 columns
179 wide. This may help you avoid going over that limit
180 (`fortran-window-create').
182 The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
183 above the current line. The comment ruler consists of two lines of
184 text that show you the locations of columns with special significance
185 in Fortran programs. Square brackets show the limits of the columns for
186 line numbers, and curly brackets show the limits of the columns for the
187 statement body. Column numbers appear above them.
189 Note that the column numbers count from zero, as always in XEmacs.
190 As a result, the numbers may not be those you are familiar with; but the
191 actual positions in the line are standard Fortran.
193 The text used to display the column ruler is the value of the
194 variable `fortran-comment-ruler'. By changing this variable, you can
197 For even more help, use `C-c C-w' (`fortran-window-create'), a
198 command which splits the current window horizontally, resulting in a
199 window 72 columns wide. When you edit in this window, you can
200 immediately see when a line gets too wide to be correct Fortran.
203 File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran
205 Fortran Keyword Abbrevs
206 -----------------------
208 Fortran mode provides many built-in abbrevs for common keywords and
209 declarations. These are the same sort of abbrevs that you can define
210 yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::.
212 The built-in abbrevs are unusual in one way: they all start with a
213 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
214 mode makes this possible by changing the syntax of semicolon to "word
217 For example, one built-in Fortran abbrev is `;c' for `continue'. If
218 you insert `;c' and then insert a punctuation character such as a space
219 or a newline, the `;c' changes automatically to `continue', provided
220 Abbrev mode is enabled.
222 Type `;?' or `;C-h' to display a list of all built-in Fortran
223 abbrevs and what they stand for.
226 File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs
231 Asm mode is a major mode for editing files of assembler code. It
232 defines these commands:
238 Insert a newline and then indent using `tab-to-tab-stop'.
241 Insert a colon and then remove the indentation from before the
242 label preceding colon. Then do `tab-to-tab-stop'.
245 Insert or align a comment.
247 The variable `asm-comment-char' specifies which character starts
248 comments in assembler syntax.
251 File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top
253 Compiling and Testing Programs
254 ******************************
256 The previous chapter discusses the Emacs commands that are useful for
257 making changes in programs. This chapter deals with commands that
258 assist in the larger process of developing and maintaining programs.
262 * Compilation:: Compiling programs in languages other than Lisp
264 * Modes: Lisp Modes. Various modes for editing Lisp programs, with
265 different facilities for running the Lisp programs.
266 * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
267 * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
268 * Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
269 * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
270 * External Lisp:: Communicating through Emacs with a separate Lisp.
273 File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running
275 Running "make", or Compilers Generally
276 ======================================
278 Emacs can run compilers for non-interactive languages like C and
279 Fortran as inferior processes, feeding the error log into an Emacs
280 buffer. It can also parse the error messages and visit the files in
281 which errors are found, moving point to the line where the error
285 Run a compiler asynchronously under Emacs, with error messages to
286 `*compilation*' buffer.
289 Run `grep' asynchronously under Emacs, with matching lines listed
290 in the buffer named `*compilation*'.
292 `M-x kill-compilation'
293 Kill the process made by the `M-x compile' command.
296 Kill the running compilation or `grep' subprocess.
299 Visit the next compiler error message or `grep' match.
301 To run `make' or another compiler, type `M-x compile'. This command
302 reads a shell command line using the minibuffer, then executes the
303 specified command line in an inferior shell with output going to the
304 buffer named `*compilation*'. By default, the current buffer's default
305 directory is used as the working directory for the execution of the
306 command; therefore, the makefile comes from this directory.
308 When the shell command line is read, the minibuffer appears
309 containing a default command line (the command you used the last time
310 you typed `M-x compile'). If you type just <RET>, the same command
311 line is used again. The first `M-x compile' provides `make -k' as the
312 default. The default is taken from the variable `compile-command'; if
313 the appropriate compilation command for a file is something other than
314 `make -k', it can be useful to have the file specify a local value for
315 `compile-command' (*note File Variables::).
317 When you start a compilation, the buffer `*compilation*' is
318 displayed in another window but not selected. Its mode line displays
319 the word `run' or `exit' in the parentheses to tell you whether
320 compilation is finished. You do not have to keep this buffer visible;
321 compilation continues in any case.
323 To kill the compilation process, type `M-x-kill-compilation'. The
324 mode line of the `*compilation*' buffer changes to say `signal' instead
325 of `run'. Starting a new compilation also kills any running
326 compilation, as only one can occur at any time. Starting a new
327 compilation prompts for confirmation before actually killing a
328 compilation that is running.
330 To parse the compiler error messages, type `C-x `' (`next-error').
331 The character following `C-x' is the grave accent, not the single
332 quote. The command displays the buffer `*compilation*' in one window
333 and the buffer in which the next error occurred in another window.
334 Point in that buffer is moved to the line where the error was found.
335 The corresponding error message is scrolled to the top of the window in
336 which `*compilation*' is displayed.
338 The first time you use `C-x `' after the start of a compilation, it
339 parses all the error messages, visits all the files that have error
340 messages, and creates markers pointing at the lines the error messages
341 refer to. It then moves to the first error message location.
342 Subsequent uses of `C-x `' advance down the data set up by the first
343 use. When the preparsed error messages are exhausted, the next `C-x `'
344 checks for any more error messages that have come in; this is useful if
345 you start editing compiler errors while compilation is still going on.
346 If no additional error messages have come in, `C-x `' reports an error.
348 `C-u C-x `' discards the preparsed error message data and parses the
349 `*compilation*' buffer again, then displays the first error. This way,
350 you can process the same set of errors again.
352 Instead of running a compiler, you can run `grep' and see the lines
353 on which matches were found. To do this, type `M-x grep' with an
354 argument line that contains the same arguments you would give to
355 `grep': a `grep'-style regexp (usually in single quotes to quote the
356 shell's special characters) followed by filenames, which may use
357 wildcard characters. The output from `grep' goes in the
358 `*compilation*' buffer. You can use `C-x `' to find the lines that
359 match as if they were compilation errors.
361 Note: a shell is used to run the compile command, but the shell is
362 not run in interactive mode. In particular, this means that the shell
363 starts up with no prompt. If you find your usual shell prompt making an
364 unsightly appearance in the `*compilation*' buffer, it means you have
365 made a mistake in your shell's initialization file (`.cshrc' or `.shrc'
366 or ...) by setting the prompt unconditionally. The shell
367 initialization file should set the prompt only if there already is a
368 prompt. Here's how to do it in `csh':
370 if ($?prompt) set prompt = ...
373 File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running
378 Emacs has four different major modes for Lisp. They are the same in
379 terms of editing commands, but differ in the commands for executing Lisp
383 The mode for editing source files of programs to run in Emacs Lisp.
384 This mode defines `C-M-x' to evaluate the current defun. *Note
387 Lisp Interaction mode
388 The mode for an interactive session with Emacs Lisp. It defines
389 <LFD> to evaluate the sexp before point and insert its value in the
390 buffer. *Note Lisp Interaction::.
393 The mode for editing source files of programs that run in other
394 dialects of Lisp than Emacs Lisp. This mode defines `C-M-x' to
395 send the current defun to an inferior Lisp process. *Note
399 The mode for an interactive session with an inferior Lisp process.
400 This mode combines the special features of Lisp mode and Shell mode
401 (*note Shell Mode::).
404 Like Lisp mode but for Scheme programs.
407 The mode for an interactive session with an inferior Scheme
411 File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
413 Libraries of Lisp Code for Emacs
414 ================================
416 Lisp code for Emacs editing commands is stored in files whose names
417 conventionally end in `.el'. This ending tells Emacs to edit them in
418 Emacs-Lisp mode (*note Lisp Modes::).
422 * Loading:: Loading libraries of Lisp code into Emacs for use.
423 * Compiling Libraries:: Compiling a library makes it load and run faster.
424 * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
427 File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
433 Load the file FILE of Lisp code.
435 `M-x load-library LIBRARY'
436 Load the library named LIBRARY.
438 `M-x locate-library LIBRARY &optional NOSUFFIX'
439 Show the full path name of Emacs library LIBRARY.
441 To execute a file of Emacs Lisp, use `M-x load-file'. This command
442 reads the file name you provide in the minibuffer, then executes the
443 contents of that file as Lisp code. It is not necessary to visit the
444 file first; in fact, this command reads the file as found on disk, not
445 the text in an Emacs buffer.
447 Once a file of Lisp code is installed in the Emacs Lisp library
448 directories, users can load it using `M-x load-library'. Programs can
449 load it by calling `load-library', or with `load', a more primitive
450 function that is similar but accepts some additional arguments.
452 `M-x load-library' differs from `M-x load-file' in that it searches
453 a sequence of directories and tries three file names in each directory.
454 The three names are: first, the specified name with `.elc' appended;
455 second, the name with `.el' appended; third, the specified name alone.
456 A `.elc' file would be the result of compiling the Lisp file into byte
457 code; if possible, it is loaded in preference to the Lisp file itself
458 because the compiled file loads and runs faster.
460 Because the argument to `load-library' is usually not in itself a
461 valid file name, file name completion is not available. In fact, when
462 using this command, you usually do not know exactly what file name will
465 The sequence of directories searched by `M-x load-library' is
466 specified by the variable `load-path', a list of strings that are
467 directory names. The elements of this list may not begin with "`~'",
468 so you must call `expand-file-name' on them before adding them to the
469 list. The default value of the list contains the directory where the
470 Lisp code for Emacs itself is stored. If you have libraries of your
471 own, put them in a single directory and add that directory to
472 `load-path'. `nil' in this list stands for the current default
473 directory, but it is probably not a good idea to put `nil' in the list.
474 If you start wishing that `nil' were in the list, you should probably
475 use `M-x load-file' for this case.
477 The variable is initialized by the EMACSLOADPATH environment
478 variable. If no value is specified, the variable takes the default value
479 specified in the file `paths.h' when Emacs was built. If a path isn't
480 specified in `paths.h', a default value is obtained from the file
481 system, near the directory in which the Emacs executable resides.
483 Like `M-x load-library', `M-x locate-library' searches the
484 directories in `load-path' to find the file that `M-x load-library'
485 would load. If the optional second argument NOSUFFIX is non-`nil', the
486 suffixes `.elc' or `.el' are not added to the specified name LIBRARY
487 (like calling `load' instead of `load-library').
489 You often do not have to give any command to load a library, because
490 the commands defined in the library are set up to "autoload" that
491 library. Running any of those commands causes `load' to be called to
492 load the library; this replaces the autoload definitions with the real
493 ones from the library.
495 If autoloading a file does not finish, either because of an error or
496 because of a `C-g' quit, all function definitions made by the file are
497 undone automatically. So are any calls to `provide'. As a
498 consequence, the entire file is loaded a second time if you use one of
499 the autoloadable commands again. This prevents problems when the
500 command is no longer autoloading but is working incorrectly because the
501 file was only partially loaded. Function definitions are undone only
502 for autoloading; explicit calls to `load' do not undo anything if
503 loading is not completed.
505 The variable `after-load-alist' takes an alist of expressions to be
506 evaluated when particular files are loaded. Each element has the form
507 `(FILENAME forms...)'. When `load' is run and the filename argument is
508 FILENAME, the forms in the corresponding element are executed at the
511 FILENAME must match exactly. Normally FILENAME is the name of a
512 library, with no directory specified, since that is how load is
513 normally called. An error in `forms' does not undo the load, but it
514 does prevent execution of the rest of the `forms'.
517 File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
522 Emacs Lisp code can be compiled into byte-code which loads faster,
523 takes up less space when loaded, and executes faster.
525 `M-x batch-byte-compile'
526 Run byte-compile-file on the files remaining on the command line.
528 `M-x byte-compile-buffer &optional BUFFER'
529 Byte-compile and evaluate contents of BUFFER (default is current
532 `M-x byte-compile-file'
533 Compile a file of Lisp code named FILENAME into a file of byte
536 `M-x byte-compile-and-load-file FILENAME'
537 Compile a file of Lisp code named FILENAME into a file of byte
540 `M-x byte-recompile-directory DIRECTORY'
541 Recompile every `.el' file in DIRECTORY that needs recompilation.
544 Print disassembled code for OBJECT on (optional) STREAM.
546 `M-x make-obsolete FUNCTION NEW'
547 Make the byte-compiler warn that FUNCTION is obsolete and NEW
548 should be used instead.
550 `byte-compile-file' creates a byte-code compiled file from an
551 Emacs-Lisp source file. The default argument for this function is the
552 file visited in the current buffer. The function reads the specified
553 file, compiles it into byte code, and writes an output file whose name
554 is made by appending `c' to the input file name. Thus, the file
555 `rmail.el' would be compiled into `rmail.elc'. To compile a file of
556 Lisp code named FILENAME into a file of byte code and then load it, use
557 `byte-compile-and-load-file'. To compile and evaluate Lisp code in a
558 given buffer, use `byte-compile-buffer'.
560 To recompile all changed Lisp files in a directory, use `M-x
561 byte-recompile-directory'. Specify just the directory name as an
562 argument. Each `.el' file that has been byte-compiled before is
563 byte-compiled again if it has changed since the previous compilation.
564 A numeric argument to this command tells it to offer to compile each
565 `.el' file that has not been compiled yet. You must answer `y' or `n'
568 You can use the function `batch-byte-compile' to invoke Emacs
569 non-interactively from the shell to do byte compilation. When you use
570 this function, the files to be compiled are specified with command-line
571 arguments. Use a shell command of the form:
573 emacs -batch -f batch-byte-compile FILES...
575 Directory names may also be given as arguments; in that case,
576 `byte-recompile-directory' is invoked on each such directory.
577 `batch-byte-compile' uses all remaining command-line arguments as file
578 or directory names, then kills the Emacs process.
580 `M-x disassemble' explains the result of byte compilation. Its
581 argument is a function name. It displays the byte-compiled code in a
582 help window in symbolic form, one instruction per line. If the
583 instruction refers to a variable or constant, that is shown, too.
586 File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
588 Converting Mocklisp to Lisp
589 ---------------------------
591 XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
592 To convert a Mocklisp file, visit it and then type `M-x
593 convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
594 in a file whose name ends in `.el' and use the new file as a Lisp
597 You cannot currently byte-compile converted Mocklisp code. The
598 reason is that converted Mocklisp code uses some special Lisp features
599 to deal with Mocklisp's incompatible ideas of how arguments are
600 evaluated and which values signify "true" or "false".
603 File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
605 Evaluating Emacs-Lisp Expressions
606 =================================
608 Lisp programs intended to be run in Emacs should be edited in
609 Emacs-Lisp mode; this will happen automatically for file names ending in
610 `.el'. By contrast, Lisp mode itself should be used for editing Lisp
611 programs intended for other Lisp systems. Emacs-Lisp mode can be
612 selected with the command `M-x emacs-lisp-mode'.
614 For testing of Lisp programs to run in Emacs, it is useful to be able
615 to evaluate part of the program as it is found in the Emacs buffer. For
616 example, if you change the text of a Lisp function definition and then
617 evaluate the definition, Emacs installs the change for future calls to
618 the function. Evaluation of Lisp expressions is also useful in any
619 kind of editing task for invoking non-interactive functions (functions
620 that are not commands).
623 Read a Lisp expression in the minibuffer, evaluate it, and print
624 the value in the minibuffer (`eval-expression').
627 Evaluate the Lisp expression before point, and print the value in
628 the minibuffer (`eval-last-sexp').
631 Evaluate the defun containing point or after point, and print the
632 value in the minibuffer (`eval-defun').
635 Evaluate all the Lisp expressions in the region.
637 `M-x eval-current-buffer'
638 Evaluate all the Lisp expressions in the buffer.
640 `M-<ESC>' (`eval-expression') is the most basic command for
641 evaluating a Lisp expression interactively. It reads the expression
642 using the minibuffer, so you can execute any expression on a buffer
643 regardless of what the buffer contains. When evaluation is complete,
644 the current buffer is once again the buffer that was current when
647 `M-<ESC>' can easily confuse users, especially on keyboards with
648 autorepeat, where it can result from holding down the <ESC> key for too
649 long. Therefore, `eval-expression' is normally a disabled command.
650 Attempting to use this command asks for confirmation and gives you the
651 option of enabling it; once you enable the command, you are no longer
652 required to confirm. *Note Disabling::.
654 In Emacs-Lisp mode, the key `C-M-x' is bound to the function
655 `eval-defun', which parses the defun containing point or following point
656 as a Lisp expression and evaluates it. The value is printed in the echo
657 area. This command is convenient for installing in the Lisp environment
658 changes that you have just made in the text of a function definition.
660 The command `C-x C-e' (`eval-last-sexp') performs a similar job but
661 is available in all major modes, not just Emacs-Lisp mode. It finds
662 the sexp before point, reads it as a Lisp expression, evaluates it, and
663 prints the value in the echo area. It is sometimes useful to type in an
664 expression and then, with point still after it, type `C-x C-e'.
666 If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
667 value by inserting it into the current buffer at point, rather than in
668 the echo area. The argument value does not matter.
670 The most general command for evaluating Lisp expressions from a
671 buffer is `eval-region'. `M-x eval-region' parses the text of the
672 region as one or more Lisp expressions, evaluating them one by one.
673 `M-x eval-current-buffer' is similar, but it evaluates the entire
674 buffer. This is a reasonable way to install the contents of a file of
675 Lisp code that you are just ready to test. After finding and fixing a
676 bug, use `C-M-x' on each function that you change, to keep the Lisp
677 world in step with the source file.
680 File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
682 The Emacs-Lisp Debugger
683 =======================
685 XEmacs contains a debugger for Lisp programs executing inside it.
686 This debugger is normally not used; many commands frequently get Lisp
687 errors when invoked in inappropriate contexts (such as `C-f' at the end
688 of the buffer) and it would be unpleasant to enter a special debugging
689 mode in this case. When you want to make Lisp errors invoke the
690 debugger, you must set the variable `debug-on-error' to non-`nil'.
691 Quitting with `C-g' is not considered an error, and `debug-on-error'
692 has no effect on the handling of `C-g'. However, if you set
693 `debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This
694 can be useful for debugging an infinite loop; type `C-g' once the loop
695 has had time to reach its steady state. `debug-on-quit' has no effect
698 You can make Emacs enter the debugger when a specified function is
699 called or at a particular place in Lisp code. Use `M-x debug-on-entry'
700 with argument FUN-NAME to have Emacs enter the debugger as soon as
701 FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
702 function stop entering the debugger when called. (Redefining the
703 function also does this.) To enter the debugger from some other place
704 in Lisp code, you must insert the expression `(debug)' there and
705 install the changed code with `C-M-x'. *Note Lisp Eval::.
707 When the debugger is entered, it displays the previously selected
708 buffer in one window and a buffer named `*Backtrace*' in another
709 window. The backtrace buffer contains one line for each level of Lisp
710 function execution currently going on. At the beginning of the buffer
711 is a message describing the reason that the debugger was invoked, for
712 example, an error message if it was invoked due to an error.
714 The backtrace buffer is read-only and is in Backtrace mode, a special
715 major mode in which letters are defined as debugger commands. The
716 usual Emacs editing commands are available; you can switch windows to
717 examine the buffer that was being edited at the time of the error, and
718 you can switch buffers, visit files, and perform any other editing
719 operations. However, the debugger is a recursive editing level (*note
720 Recursive Edit::); it is a good idea to return to the backtrace buffer
721 and explictly exit the debugger when you don't want to use it any more.
722 Exiting the debugger kills the backtrace buffer.
724 The contents of the backtrace buffer show you the functions that are
725 executing and the arguments that were given to them. It also allows you
726 to specify a stack frame by moving point to the line describing that
727 frame. The frame whose line point is on is considered the "current
728 frame". Some of the debugger commands operate on the current frame.
729 Debugger commands are mainly used for stepping through code one
730 expression at a time. Here is a list of them:
733 Exit the debugger and continue execution. In most cases,
734 execution of the program continues as if the debugger had never
735 been entered (aside from the effect of any variables or data
736 structures you may have changed while inside the debugger). This
737 includes entry to the debugger due to function entry or exit,
738 explicit invocation, and quitting or certain errors. Most errors
739 cannot be continued; trying to continue an error usually causes
740 the same error to occur again.
743 Continue execution, but enter the debugger the next time a Lisp
744 function is called. This allows you to step through the
745 subexpressions of an expression, and see what the subexpressions
746 do and what values they compute.
748 When you enter the debugger this way, Emacs flags the stack frame
749 for the function call from which you entered. The same function
750 is then called when you exit the frame. To cancel this flag, use
754 Set up to enter the debugger when the current frame is exited.
755 Frames that invoke the debugger on exit are flagged with stars.
758 Don't enter the debugger when the current frame is exited. This
759 cancels a `b' command on a frame.
762 Read a Lisp expression in the minibuffer, evaluate it, and print
763 the value in the echo area. This is equivalent to the command
764 `M-<ESC>', except that `e' is not normally disabled like `M-<ESC>'.
767 Terminate the program being debugged; return to top-level Emacs
770 If the debugger was entered due to a `C-g' but you really want to
771 quit, not to debug, use the `q' command.
774 Return a value from the debugger. The value is computed by
775 reading an expression with the minibuffer and evaluating it.
777 The value returned by the debugger makes a difference when the
778 debugger was invoked due to exit from a Lisp call frame (as
779 requested with `b'); then the value specified in the `r' command
780 is used as the value of that frame.
782 The debugger's return value also matters with many errors. For
783 example, `wrong-type-argument' errors will use the debugger's
784 return value instead of the invalid argument; `no-catch' errors
785 will use the debugger value as a throw tag instead of the tag that
786 was not found. If an error was signaled by calling the Lisp
787 function `signal', the debugger's return value is returned as the
791 File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
793 Lisp Interaction Buffers
794 ========================
796 The buffer `*scratch*', which is selected when Emacs starts up, is
797 provided for evaluating Lisp expressions interactively inside Emacs.
798 Both the expressions you evaluate and their output goes in the buffer.
800 The `*scratch*' buffer's major mode is Lisp Interaction mode, which
801 is the same as Emacs-Lisp mode except for one command, <LFD>. In
802 Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
803 mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
804 the Lisp expression before point, evaluates it, and inserts the value
805 in printed representation before point.
807 The way to use the `*scratch*' buffer is to insert Lisp expressions
808 at the end, ending each one with <LFD> so that it will be evaluated.
809 The result is a complete typescript of the expressions you have
810 evaluated and their values.
812 The rationale for this feature is that Emacs must have a buffer when
813 it starts up, but that buffer is not useful for editing files since a
814 new buffer is made for every file that you visit. The Lisp interpreter
815 typescript is the most useful thing I can think of for the initial
816 buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
820 File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
822 Running an External Lisp
823 ========================
825 Emacs has facilities for running programs in other Lisp systems.
826 You can run a Lisp process as an inferior of Emacs, and pass
827 expressions to it to be evaluated. You can also pass changed function
828 definitions directly from the Emacs buffers in which you edit the Lisp
829 programs to the inferior Lisp process.
831 To run an inferior Lisp process, type `M-x run-lisp'. This runs the
832 program named `lisp', the same program you would run by typing `lisp'
833 as a shell command, with both input and output going through an Emacs
834 buffer named `*lisp*'. In other words, any "terminal output" from Lisp
835 will go into the buffer, advancing point, and any "terminal input" for
836 Lisp comes from text in the buffer. To give input to Lisp, go to the
837 end of the buffer and type the input, terminated by <RET>. The
838 `*lisp*' buffer is in Inferior Lisp mode, which has all the special
839 characteristics of Lisp mode and Shell mode (*note Shell Mode::).
841 Use Lisp mode to run the source files of programs in external Lisps.
842 You can select this mode with `M-x lisp-mode'. It is used automatically
843 for files whose names end in `.l' or `.lisp', as most Lisp systems
846 When you edit a function in a Lisp program you are running, the
847 easiest way to send the changed definition to the inferior Lisp process
848 is the key `C-M-x'. In Lisp mode, this key runs the function
849 `lisp-send-defun', which finds the defun around or following point and
850 sends it as input to the Lisp process. (Emacs can send input to any
851 inferior process regardless of what buffer is current.)
853 Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
854 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
855 programs to be run in Emacs): in both modes it has the effect of
856 installing the function definition that point is in, but the way of
857 doing so is different according to where the relevant Lisp environment
858 is found. *Note Lisp Modes::.
861 File: xemacs.info, Node: Packages, Next: Abbrevs, Prev: Running, Up: Top
866 The XEmacs 21 distribution comes only with a very basic set of
867 built-in modes and packages. Most of the packages that were part of
868 the distribution of earlier versions of XEmacs are now available
869 separately. The installer as well as the user can choose which
870 packages to install; the actual installation process is easy. This
871 gives an installer the ability to tailor an XEmacs installation for
872 local needs with safe removal of unnecessary code.
876 * Package Terminology:: Understanding different kinds of packages.
877 * Using Packages:: How to install and use packages.
878 * Building Packages:: Building packages from sources.
881 File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages
886 There are two main flavors of packages.
888 * Regular Packages A regular package is one in which multiple files
889 are involved and one may not in general safely remove any of them.
891 * Single-File Packages A single-file package is an aggregate
892 collection of thematically related but otherwise independent lisp
893 files. These files are bundled together for download convenience
894 and individual files may be deleted at will without any loss of
897 Package Distributions
898 ---------------------
900 XEmacs Lisp packages are distributed in two ways, depending on the
901 intended use. Binary Packages are for installers and end-users and may
902 be installed directly into an XEmacs package directory. Source Packages
903 are for developers and include all files necessary for rebuilding
904 bytecompiled lisp and creating tarballs for distribution.
909 Binary packages may be installed directly into an XEmacs package
915 Source packages contain all of the Package author's (where
916 appropriate in regular packages) source code plus all of the files
917 necessary to build distribution tarballs (Unix Tar format files,
918 gzipped for space savings).
921 File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
926 When you first download XEmacs 21, you will usually first grab the
927 "core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the
928 21.0 by the current version number.) The core distribution contains
929 the sources of XEmacs and a minimal set of Emacs Lisp files, which are
930 in the subdirectory named `lisp'. This subdirectory used to contain
931 all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
932 space, most non-essential packages were made optional.
934 Choosing the Packages You Need
935 ------------------------------
937 The available packages can currently be found in the same ftp
938 directory where you grabbed the core distribution from, and are located
939 in the subdirectory `packages/binary-packages'. Package file names
940 follow the naming convention `<package-name>-<version>-pkg.tar.gz'.
942 If you have EFS *Note (EFS)::, packages can be installed over the
943 network. Alternatively, if you have copies of the packages locally,
944 you can install packages from a local disk or CDROM.
946 The file `etc/PACKAGES' in the core distribution contains a list of
947 the packages available at the time of the XEmacs release. Packages are
948 also listed on the `Options' menu under:
950 Options->Customize->Emacs->Packages
952 However, don't select any of these menu picks unless you actually
953 want to install the given package (and have properly configured your
956 You can also get a list of available packages, and whether or not
957 they are installed, using the visual package browser and installer.
958 You can access it via the menus:
960 Options->Manage Packages->List & Install
962 Or, you can get to it via the keyboard:
964 M-x pui-list-packages
966 Hint to system administrators of multi-user systems: it might be a
967 good idea to install all packages and not interfere with the wishes of
970 If you can't find which package provides the feature you require, try
971 using the `package-get-package-provider' function. Eg., if you know
972 that you need `thingatpt', type:
974 M-x package-get-package-provider RET thingatpt
976 which will return something like (fsf-compat "1.06"). You can the use
977 one of the methods above for installing the package you want.
979 XEmacs and Installing Packages
980 ------------------------------
982 Normally, packages are installed over the network, using EFS *Note
983 (EFS)::. However, you may not have network access, or you may already
984 have some or all of the packages on a local disk, such as a CDROM. If
985 you want to install from a local disk, you must first tell XEmacs where
986 to find the package binaries. This is done by adding a line like the
987 following to your `.emacs' file:
989 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
992 Here, you'd change `/my/path/to/package/binaries' to be the path to
993 your local package binaries. Next, restart XEmacs, and you're ready to
994 go (advanced users can just re-evaluate the sexp).
996 If you are installing from a temporary, one-time directory, you can
997 also add these directory names to `package-get-remote' using:
999 M-x pui-add-install-directory
1001 Note, however, that any directories added using this function are not
1002 saved; this information will be lost when you quit XEmacs.
1004 If you're going to install over the network, you only have to insure
1005 that EFS *Note (EFS):: works, and that it can get outside a firewall, if
1006 you happen to be behind one. You shouldn't have to do anything else;
1007 XEmacs already knows where to go. However you can add your own mirrors
1008 to this list. See `package-get-remote'.
1010 The easiest way to install a package is to use the visual package
1011 browser and installer, using the menu pick:
1013 Options->Manage Packages->List & Install
1015 Options->Manage Packages->Using Custom->Select-> ...
1017 You can also access it using the keyboard:
1019 M-x pui-list-packages
1021 The visual package browser will then display a list of all packages.
1022 Help information will be displayed at the very bottom of the buffer; you
1023 may have to scroll down to see it. You can also press `?' to get the
1024 same help. From this buffer, you can tell the package status by the
1025 character in the first column:
1028 The package has not been installed.
1031 The package has been installed, but a newer version is available.
1032 The current version is out-of-date.
1035 The package has been marked for installation/update.
1037 If there is no character in the first column, the package has been
1038 installed and is up-to-date.
1040 From here, you can select or unselect packages for installation using
1041 the <RET> key, the `Mouse-2' button or selecting "Select" from the
1042 (Popup) Menu. Once you've finished selecting the packages, you can
1043 press the `x' key (or use the menu) to actually install the packages.
1044 Note that you will have to restart XEmacs for XEmacs to recognize any
1050 Display simple help.
1054 Toggle between selecting and unselecting a package for
1058 Install selected packages.
1061 View, in the minibuffer, additional information about the package,
1062 such as the package date (not the build date) and the package
1063 author. Moving the mouse over a package name will also do the
1067 Toggle between verbose and non-verbose package display.
1070 Refresh the package display.
1073 Kill the package buffer.
1075 Moving the mouse over a package will also cause additional
1076 information about the package to be displayed in the minibuffer.
1078 Other package installation interfaces
1079 -------------------------------------
1081 For an alternative package interface, you can select packages from
1082 the customize menus, under:
1084 Options->Customize->Emacs->Packages-> ...
1086 Options->Manage Packages->Using Custom->Select-> ...
1088 Set their state to on, and then do:
1090 Options->Manage Packages->Using Custom->Update Packages
1092 This will automatically retrieve the packages you have selected from
1093 the XEmacs ftp site or your local disk, and install them into XEmacs.
1094 Additionally it will update any packages you already have installed to
1095 the newest version. Note that if a package is newly installed you will
1096 have to restart XEmacs for the change to take effect.
1098 You can also install packages using a semi-manual interface:
1100 M-x package-get-all <return>
1102 Enter the name of the package (e.g., `prog-modes'), and XEmacs will
1103 search for the latest version (as listed in the lisp file
1104 `lisp/package-get-base.el'), and install it and any packages that it
1107 Manual Binary Package Installation
1108 ----------------------------------
1110 Pre-compiled, binary packages can be installed in either a system
1111 package directory (this is determined when XEmacs is compiled), or in
1112 one of the following subdirectories of your `$HOME' directory:
1114 ~/.xemacs/mule-packages
1115 ~/.xemacs/xemacs-packages
1117 Packages in the former directory will only be found by a Mule-enabled
1120 XEmacs does not have to be running to install binary packages,
1121 although XEmacs will not know about any newly-installed packages until
1122 you restart XEmacs. Note, however, that installing a newer version of a
1123 package while XEmacs is running could cause strange errors in XEmacs;
1124 it's best to exit XEmacs before upgrading an existing package.
1126 To install binary packages manually:
1128 1. Download the package(s) that you want to install. Each binary
1129 package will typically be a gzip'd tarball.
1131 2. Decide where to install the packages: in the system package
1132 directory, or in `~/.xemacs/mule-packages' or
1133 `~/.xemacs/xemacs-packages', respectively. If you want to install
1134 the packages in the system package directory, make sure you can
1135 write into that directory. If you want to install in your `$HOME'
1136 directory, create the directory, `~/.xemacs/mule-packages' or
1137 `~/.xemacs/xemacs-packages', respectively.
1139 3. Next, `cd' to the directory under which you want to install the
1142 4. From this directory, uncompress and extract each of the gzip'd
1143 tarballs that you downloaded in step 1. Unix and Cygnus cygwin
1144 users will typically do this using the commands:
1146 gunzip < package.tar.gz | tar xvf -
1148 Above, replace `package.tar.gz' with the filename of the package
1149 that you downloaded in step 1.
1151 Of course, if you use GNU `tar', you could also use:
1153 tar xvzf package.tar.gz
1155 5. That's it. Quit and restart XEmacs to get it to recognize any new
1156 or changed packages.