![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs-9 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / emacs / info|
Return to emacs-9 CVS log | Up to [Apple XNU] / GNUtools / emacs / info |
1.1 root 1: This is Info file ../info/emacs, produced by Makeinfo-1.49 from the
2: input file emacs.texi.
3:
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of this
9: manual provided the copyright notice and this permission notice are
10: preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of
13: this manual under the conditions for verbatim copying, provided also
14: that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
15: General Public License" are included exactly as in the original, and
16: provided that the entire resulting derived work is distributed under the
17: terms of a permission notice identical to this one.
18:
19: Permission is granted to copy and distribute translations of this
20: manual into another language, under the above conditions for modified
21: versions, except that the sections entitled "The GNU Manifesto",
22: "Distribution" and "GNU General Public License" may be included in a
23: translation approved by the author instead of in the original English.
24:
25:
26: File: emacs, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Compiling/Testing
27:
28: Evaluating Emacs-Lisp Expressions
29: =================================
30:
31: Lisp programs intended to be run in Emacs should be edited in
32: Emacs-Lisp mode; this will happen automatically for file names ending
33: in `.el'. By contrast, Lisp mode itself is used for editing Lisp
34: programs intended for other Lisp systems. Emacs-Lisp mode can be
35: selected with the command `M-x emacs-lisp-mode'.
36:
37: For testing of Lisp programs to run in Emacs, it is useful to be
38: able to evaluate part of the program as it is found in the Emacs
39: buffer. For example, after changing the text of a Lisp function
40: definition, evaluating the definition installs the change for future
41: calls to the function. Evaluation of Lisp expressions is also useful in
42: any kind of editing task for invoking noninteractive functions
43: (functions that are not commands).
44:
45: `M-ESC'
46: Read a Lisp expression in the minibuffer, evaluate it, and print
47: the value in the minibuffer (`eval-expression').
48:
49: `C-x C-e'
50: Evaluate the Lisp expression before point, and print the value in
51: the minibuffer (`eval-last-sexp').
52:
53: `C-M-x'
54: Evaluate the defun containing or after point, and print the value
55: in the minibuffer (`eval-defun').
56:
57: `M-x eval-region'
58: Evaluate all the Lisp expressions in the region.
59:
60: `M-x eval-current-buffer'
61: Evaluate all the Lisp expressions in the buffer.
62:
63: `M-ESC' (`eval-expression') is the most basic command for evaluating
64: a Lisp expression interactively. It reads the expression using the
65: minibuffer, so you can execute any expression on a buffer regardless of
66: what the buffer contains. When the expression is evaluated, the current
67: buffer is once again the buffer that was current when `M-ESC' was typed.
68:
69: `M-ESC' can easily confuse users who do not understand it,
70: especially on keyboards with autorepeat where it can result from holding
71: down the ESC key for too long. Therefore, `eval-expression' is
72: normally a disabled command. Attempting to use this command asks for
73: confirmation and gives you the option of enabling it; once you enable
74: the command, confirmation will no longer be required for it. *Note
75: Disabling::.
76:
77: In Emacs-Lisp mode, the key `C-M-x' is bound to the function
78: `eval-defun', which parses the defun containing or following point as a
79: Lisp expression and evaluates it. The value is printed in the echo
80: area. This command is convenient for installing in the Lisp
81: environment changes that you have just made in the text of a function
82: definition.
83:
84: The command `C-x C-e' (`eval-last-sexp') performs a similar job but
85: is available in all major modes, not just Emacs-Lisp mode. It finds
86: the sexp before point, reads it as a Lisp expression, evaluates it, and
87: prints the value in the echo area. It is sometimes useful to type in an
88: expression and then, with point still after it, type `C-x C-e'.
89:
90: If `C-M-x' or `C-x C-e' is given a numeric argument, it prints the
91: value by insertion into the current buffer at point, rather than in the
92: echo area. The argument value does not matter.
93:
94: The most general command for evaluating Lisp expressions from a
95: buffer is `eval-region'. `M-x eval-region' parses the text of the
96: region as one or more Lisp expressions, evaluating them one by one.
97: `M-x eval-current-buffer' is similar but evaluates the entire buffer.
98: This is a reasonable way to install the contents of a file of Lisp code
99: that you are just ready to test. After finding and fixing a bug, use
100: `C-M-x' on each function that you change, to keep the Lisp world in
101: step with the source file.
102:
103:
104: File: emacs, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Compiling/Testing
105:
106: The Emacs-Lisp Debugger
107: =======================
108:
109: GNU Emacs contains a debugger for Lisp programs executing inside it.
110: This debugger is normally not used; many commands frequently get Lisp
111: errors when invoked in inappropriate contexts (such as `C-f' at the end
112: of the buffer) and it would be very unpleasant for that to enter a
113: special debugging mode. When you want to make Lisp errors invoke the
114: debugger, you must set the variable `debug-on-error' to non-`nil'.
115: Quitting with `C-g' is not considered an error, and `debug-on-error'
116: has no effect on the handling of `C-g'. However, if you set
117: `debug-on-quit' non-`nil', `C-g' will invoke the debugger. This can be
118: useful for debugging an infinite loop; type `C-g' once the loop has had
119: time to reach its steady state. `debug-on-quit' has no effect on
120: errors.
121:
122: You can also cause the debugger to be entered when a specified
123: function is called, or at a particular place in Lisp code. Use `M-x
124: debug-on-entry' with argument FUN-NAME to cause function FUN-NAME to
125: enter the debugger as soon as it is called. Use `M-x
126: cancel-debug-on-entry' to make the function stop entering the debugger
127: when called. (Redefining the function also does this.) To enter the
128: debugger from some other place in Lisp code, you must insert the
129: expression `(debug)' there and install the changed code with `C-M-x'.
130: *Note Lisp Eval::.
131:
132: When the debugger is entered, it displays the previously selected
133: buffer in one window and a buffer named `*Backtrace*' in another
134: window. The backtrace buffer contains one line for each level of Lisp
135: function execution currently going on. At the beginning of this buffer
136: is a message describing the reason that the debugger was invoked (such
137: as, what error message if it was invoked due to an error).
138:
139: The backtrace buffer is read-only, and is in a special major mode,
140: Backtrace mode, in which letters are defined as debugger commands. The
141: usual Emacs editing commands are available; you can switch windows to
142: examine the buffer that was being edited at the time of the error, and
143: you can also switch buffers, visit files, and do any other sort of
144: editing. However, the debugger is a recursive editing level (*note
145: Recursive Edit::.) and it is wise to go back to the backtrace buffer
146: and exit the debugger officially when you don't want to use it any
147: more. Exiting the debugger kills the backtrace buffer.
148:
149: The contents of the backtrace buffer show you the functions that are
150: executing and the arguments that were given to them. It has the
151: additional purpose of allowing you to specify a stack frame by moving
152: point to the line describing that frame. The frame whose line point is
153: on is considered the "current frame". Some of the debugger commands
154: operate on the current frame. Debugger commands are mainly used for
155: stepping through code an expression at a time. Here is a list of them.
156:
157: `c'
158: Exit the debugger and continue execution. In most cases,
159: execution of the program continues as if the debugger had never
160: been entered (aside from the effect of any variables or data
161: structures you may have changed while inside the debugger). This
162: includes entry to the debugger due to function entry or exit,
163: explicit invocation, quitting or certain errors. Most errors
164: cannot be continued; trying to continue one of them causes the
165: same error to occur again.
166:
167: `d'
168: Continue execution, but enter the debugger the next time a Lisp
169: function is called. This allows you to step through the
170: subexpressions of an expression, seeing what values the
171: subexpressions compute and what else they do.
172:
173: The stack frame made for the function call which enters the
174: debugger in this way will be flagged automatically for the
175: debugger to be called when the frame is exited. You can use the
176: `u' command to cancel this flag.
177:
178: `b'
179: Set up to enter the debugger when the current frame is exited.
180: Frames that will invoke the debugger on exit are flagged with
181: stars.
182:
183: `u'
184: Don't enter the debugger when the current frame is exited. This
185: cancels a `b' command on that frame.
186:
187: `e'
188: Read a Lisp expression in the minibuffer, evaluate it, and print
189: the value in the echo area. This is the same as the command
190: `M-ESC', except that `e' is not normally disabled like `M-ESC'.
191:
192: `q'
193: Terminate the program being debugged; return to top-level Emacs
194: command execution.
195:
196: If the debugger was entered due to a `C-g' but you really want to
197: quit, not to debug, use the `q' command.
198:
199: `r'
200: Return a value from the debugger. The value is computed by
201: reading an expression with the minibuffer and evaluating it.
202:
203: The value returned by the debugger makes a difference when the
204: debugger was invoked due to exit from a Lisp call frame (as
205: requested with `b'); then the value specified in the `r' command
206: is used as the value of that frame.
207:
208: The debugger's return value also matters with many errors. For
209: example, `wrong-type-argument' errors will use the debugger's
210: return value instead of the invalid argument; `no-catch' errors
211: will use the debugger value as a throw tag instead of the tag that
212: was not found. If an error was signaled by calling the Lisp
213: function `signal', the debugger's return value is returned as the
214: value of `signal'.
215:
216:
217: File: emacs, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Compiling/Testing
218:
219: Lisp Interaction Buffers
220: ========================
221:
222: The buffer `*scratch*' which is selected when Emacs starts up is
223: provided for evaluating Lisp expressions interactively inside Emacs.
224: Both the expressions you evaluate and their output goes in the buffer.
225:
226: The `*scratch*' buffer's major mode is Lisp Interaction mode, which
227: is the same as Emacs-Lisp mode except for one command, LFD. In
228: Emacs-Lisp mode, LFD is an indentation command, as usual. In Lisp
229: Interaction mode, LFD is bound to `eval-print-last-sexp'. This
230: function reads the Lisp expression before point, evaluates it, and
231: inserts the value in printed representation before point.
232:
233: Thus, the way to use the `*scratch*' buffer is to insert Lisp
234: expressions at the end, ending each one with LFD so that it will be
235: evaluated. The result is a complete typescript of the expressions you
236: have evaluated and their values.
237:
238: The rationale for this feature is that Emacs must have a buffer when
239: it starts up, but that buffer is not useful for editing files since a
240: new buffer is made for every file that you visit. The Lisp interpreter
241: typescript is the most useful thing I can think of for the initial
242: buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
243: Interaction mode.
244:
245:
246: File: emacs, Node: External Lisp, Prev: Lisp Interaction, Up: Compiling/Testing
247:
248: Running an External Lisp
249: ========================
250:
251: Emacs has facilities for running programs in other Lisp systems.
252: You can run a Lisp process as an inferior of Emacs, and pass
253: expressions to it to be evaluated. You can also pass changed function
254: definitions directly from the Emacs buffers in which you edit the Lisp
255: programs to the inferior Lisp process.
256:
257: To run an inferior Lisp process, type `M-x run-lisp'. This runs the
258: program named `lisp', the same program you would run by typing `lisp'
259: as a shell command, with both input and output going through an Emacs
260: buffer named `*lisp*'. That is to say, any "terminal output" from Lisp
261: will go into the buffer, advancing point, and any "terminal input" for
262: Lisp comes from text in the buffer. To give input to Lisp, go to the
263: end of the buffer and type the input, terminated by RET. The `*lisp*'
264: buffer is in Inferior Lisp mode, a mode which has all the special
265: characteristics of Lisp mode and Shell mode (*note Shell Mode::.).
266:
267: For the source files of programs to run in external Lisps, use Lisp
268: mode. This mode can be selected with `M-x lisp-mode', and is used
269: automatically for files whose names end in `.l' or `.lisp', as most Lisp
270: systems usually expect.
271:
272: When you edit a function in a Lisp program you are running, the
273: easiest way to send the changed definition to the inferior Lisp process
274: is the key `C-M-x'. In Lisp mode, this runs the function
275: `lisp-send-defun', which finds the defun around or following point and
276: sends it as input to the Lisp process. (Emacs can send input to any
277: inferior process regardless of what buffer is current.)
278:
279: Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
280: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
281: programs to be run in Emacs): in both modes it has the effect of
282: installing the function definition that point is in, but the way of
283: doing so is different according to where the relevant Lisp environment
284: is found. *Note Lisp Modes::.
285:
286:
287: File: emacs, Node: Abbrevs, Next: Picture, Prev: Compiling/Testing, Up: Top
288:
289: Abbrevs
290: *******
291:
292: An "abbrev" is a word which "expands", if you insert it, into some
293: different text. Abbrevs are defined by the user to expand in specific
294: ways. For example, you might define `foo' as an abbrev expanding to
295: `find outer otter'. With this abbrev defined, you would be able to get
296: `find outer otter ' into the buffer by typing `f o o SPC'.
297:
298: Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
299: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
300: but they do not expand until Abbrev mode is enabled again. The command
301: `M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
302: turns Abbrev mode on if the argument is positive, off otherwise. *Note
303: Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
304: when the variable is non-`nil'. The variable `abbrev-mode'
305: automatically becomes local to the current buffer when it is set.
306:
307: Abbrev definitions can be "mode-specific"--active only in one major
308: mode. Abbrevs can also have "global" definitions that are active in
309: all major modes. The same abbrev can have a global definition and
310: various mode-specific definitions for different major modes. A mode
311: specific definition for the current major mode overrides a global
312: definition.
313:
314: Abbrevs can be defined interactively during the editing session.
315: Lists of abbrev definitions can also be saved in files and reloaded in
316: later sessions. Some users keep extensive lists of abbrevs that they
317: load in every session.
318:
319: A second kind of abbreviation facility is called the "dynamic
320: expansion". Dynamic abbrev expansion happens only when you give an
321: explicit command and the result of the expansion depends only on the
322: current contents of the buffer. *Note Dynamic Abbrevs::.
323:
324: * Menu:
325:
326: * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
327: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
328: * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
329: * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
330: * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
331:
332:
333: File: emacs, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
334:
335: Defining Abbrevs
336: ================
337:
338: `C-x +'
339: Define an abbrev to expand into some text before point
340: (`add-global-abbrev').
341:
342: `C-x C-a'
343: Similar, but define an abbrev available only in the current major
344: mode (`add-mode-abbrev').
345:
346: `C-x -'
347: Define a word in the buffer as an abbrev
348: (`inverse-add-global-abbrev').
349:
350: `C-x C-h'
351: Define a word in the buffer as a mode-specific abbrev
352: (`inverse-add-mode-abbrev').
353:
354: `M-x kill-all-abbrevs'
355: After this command, there are no abbrev definitions in effect.
356:
357: The usual way to define an abbrev is to enter the text you want the
358: abbrev to expand to, position point after it, and type `C-x +'
359: (`add-global-abbrev'). This reads the abbrev itself using the
360: minibuffer, and then defines it as an abbrev for one or more words
361: before point. Use a numeric argument to say how many words before
362: point should be taken as the expansion. For example, to define the
363: abbrev `foo' as mentioned above, insert the text `find outer otter' and
364: then type `C-u 3 C-x + f o o RET'.
365:
366: An argument of zero to `C-x +' means to use the contents of the
367: region as the expansion of the abbrev being defined.
368:
369: The command `C-x C-a' (`add-mode-abbrev') is similar, but defines a
370: mode-specific abbrev. Mode specific abbrevs are active only in a
371: particular major mode. `C-x C-a' defines an abbrev for the major mode
372: in effect at the time `C-x C-a' is typed. The arguments work the same
373: as for `C-x +'.
374:
375: If the text of the abbrev you want is already in the buffer instead
376: of the expansion, use command `C-x -' (`inverse-add-global-abbrev')
377: instead of `C-x +', or use `C-x C-h' (`inverse-add-mode-abbrev')
378: instead of `C-x C-a'. These commands are called "inverse" because they
379: invert the meaning of the argument found in the buffer and the argument
380: read using the minibuffer.
381:
382: To change the definition of an abbrev, just add the new definition.
383: You will be asked to confirm if the abbrev has a prior definition. To
384: remove an abbrev definition, give a negative argument to `C-x +' or `C-x
385: C-a'. You must choose the command to specify whether to kill a global
386: definition or a mode-specific definition for the current mode, since
387: those two definitions are independent for one abbrev.
388:
389: `M-x kill-all-abbrevs' removes all the abbrev definitions there are.
390:
391:
392: File: emacs, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
393:
394: Controlling Abbrev Expansion
395: ============================
396:
397: An abbrev expands whenever it is present in the buffer just before
398: point and a self-inserting punctuation character (SPC, comma, etc.) is
399: typed. Most often the way an abbrev is used is to insert the abbrev
400: followed by punctuation.
401:
402: Abbrev expansion preserves case; thus, `foo' expands into `find
403: outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
404: OTTER' or `Find Outer Otter' according to the variable
405: `abbrev-all-caps' (a non-`nil' value chooses the first of the two
406: expansions).
407:
408: These two commands are used to control abbrev expansion:
409:
410: `M-''
411: Separate a prefix from a following abbrev to be expanded
412: (`abbrev-prefix-mark').
413:
414: `C-x ''
415: Expand the abbrev before point (`expand-abbrev'). This is
416: effective even when Abbrev mode is not enabled.
417:
418: `M-x unexpand-abbrev'
419: Undo last abbrev expansion.
420:
421: `M-x expand-region-abbrevs'
422: Expand some or all abbrevs found in the region.
423:
424: You may wish to expand an abbrev with a prefix attached; for
425: example, if `cnst' expands into `construction', you might want to use
426: it to enter `reconstruction'. It does not work to type `recnst',
427: because that is not necessarily a defined abbrev. What does work is to
428: use the command `M-'' (`abbrev-prefix-mark') in between the prefix `re'
429: and the abbrev `cnst'. First, insert `re'. Then type `M-''; this
430: inserts a minus sign in the buffer to indicate that it has done its
431: work. Then insert the abbrev `cnst'; the buffer now contains
432: `re-cnst'. Now insert a punctuation character to expand the abbrev
433: `cnst' into `construction'. The minus sign is deleted at this point,
434: because `M-'' left word for this to be done. The resulting text is the
435: desired `reconstruction'.
436:
437: If you actually want the text of the abbrev in the buffer, rather
438: than its expansion, you can accomplish this by inserting the following
439: punctuation with `C-q'. Thus, `foo C-q -' leaves `foo-' in the buffer.
440:
441: If you expand an abbrev by mistake, you can undo the expansion
442: (replace the expansion by the original abbrev text) with `M-x
443: unexpand-abbrev'. `C-_' (`undo') can also be used to undo the
444: expansion; but first it will undo the insertion of the following
445: punctuation character!
446:
447: `M-x expand-region-abbrevs' searches through the region for defined
448: abbrevs, and for each one found offers to replace it with its expansion.
449: This command is useful if you have typed in text using abbrevs but
450: forgot to turn on Abbrev mode first. It may also be useful together
451: with a special set of abbrev definitions for making several global
452: replacements at once. This command is effective even if Abbrev mode is
453: not enabled.
454:
455:
456: File: emacs, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
457:
458: Examining and Editing Abbrevs
459: =============================
460:
461: `M-x list-abbrevs'
462: Print a list of all abbrev definitions.
463:
464: `M-x edit-abbrevs'
465: Edit a list of abbrevs; you can add, alter or remove definitions.
466:
467: The output from `M-x list-abbrevs' looks like this:
468:
469: (lisp-mode-abbrev-table)
470: "dk" 0 "define-key"
471: (global-abbrev-table)
472: "dfn" 0 "definition"
473:
474: (Some blank lines of no semantic significance, and some other abbrev
475: tables, have been omitted.)
476:
477: A line containing a name in parentheses is the header for abbrevs in
478: a particular abbrev table; `global-abbrev-table' contains all the global
479: abbrevs, and the other abbrev tables that are named after major modes
480: contain the mode-specific abbrevs.
481:
482: Within each abbrev table, each nonblank line defines one abbrev. The
483: word at the beginning is the abbrev. The number that appears is the
484: number of times the abbrev has been expanded. Emacs keeps track of
485: this to help you see which abbrevs you actually use, in case you decide
486: to eliminate those that you don't use often. The string at the end of
487: the line is the expansion.
488:
489: `M-x edit-abbrevs' allows you to add, change or kill abbrev
490: definitions by editing a list of them in an Emacs buffer. The list has
491: the same format described above. The buffer of abbrevs is called
492: `*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key
493: `C-c C-c' to install the abbrev definitions as specified in the buffer.
494: The command that does this is `edit-abbrevs-redefine'. Any abbrevs
495: not described in the buffer are eliminated when this is done.
496:
497: `edit-abbrevs' is actually the same as `list-abbrevs' except that it
498: selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely displays
499: it in another window.
500:
501:
502: File: emacs, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
503:
504: Saving Abbrevs
505: ==============
506:
507: These commands allow you to keep abbrev definitions between editing
508: sessions.
509:
510: `M-x write-abbrev-file'
511: Write a file describing all defined abbrevs.
512:
513: `M-x read-abbrev-file'
514: Read such a file and define abbrevs as specified there.
515:
516: `M-x quietly-read-abbrev-file'
517: Similar but do not display a message about what is going on.
518:
519: `M-x define-abbrevs'
520: Define abbrevs from buffer.
521:
522: `M-x insert-abbrevs'
523: Insert all abbrevs and their expansions into the buffer.
524:
525: `M-x write-abbrev-file' reads a file name using the minibuffer and
526: writes a description of all current abbrev definitions into that file.
527: The text stored in the file looks like the output of `M-x list-abbrevs'.
528: This is used to save abbrev definitions for use in a later session.
529:
530: `M-x read-abbrev-file' reads a file name using the minibuffer and
531: reads the file, defining abbrevs according to the contents of the file.
532: `M-x quietly-read-abbrev-file' is the same except that it does not
533: display a message in the echo area saying that it is doing its work; it
534: is actually useful primarily in the `.emacs' file. If an empty
535: argument is given to either of these functions, the file name used is
536: the value of the variable `abbrev-file-name', which is by default
537: `"~/.abbrev_defs"'.
538:
539: Emacs will offer to save abbrevs automatically if you have changed
540: any of them, whenever it offers to save all files (for `C-x s' or `C-x
541: C-c'). This feature can be inhibited by setting the variable
542: `save-abbrevs' to `nil'.
543:
544: The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
545: similar to the previous commands but work on text in an Emacs buffer.
546: `M-x insert-abbrevs' inserts text into the current buffer before point,
547: describing all current abbrev definitions; `M-x define-abbrevs' parses
548: the entire current buffer and defines abbrevs accordingly.
549:
550:
551: File: emacs, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
552:
553: Dynamic Abbrev Expansion
554: ========================
555:
556: The abbrev facility described above operates automatically as you
557: insert text, but all abbrevs must be defined explicitly. By contrast,
558: "dynamic abbrevs" allow the meanings of abbrevs to be determined
559: automatically from the contents of the buffer, but dynamic abbrev
560: expansion happens only when you request it explicitly.
561:
562: `M-/'
563: Expand the word in the buffer before point as a "dynamic abbrev",
564: by searching in the buffer for words starting with that
565: abbreviation (`dabbrev-expand').
566:
567: For example, if the buffer contains `does this follow ' and you type
568: `f o M-/', the effect is to insert `follow' because that is the last
569: word in the buffer that starts with `fo'. A numeric argument to `M-/'
570: says to take the second, third, etc. distinct expansion found looking
571: backward from point. Repeating `M-/' searches for an alternative
572: expansion by looking farther back. After the part of the buffer
573: preceding point has been considered, the part of the buffer after point
574: is searched.
575:
576: Dynamic abbrev expansion is completely independent of Abbrev mode;
577: the expansion of a word with `M-/' is completely independent of whether
578: it has a definition as an ordinary abbrev.
579:
580:
581: File: emacs, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top
582:
583: Editing Pictures
584: ****************
585:
586: If you want to create a picture made out of text characters (for
587: example, a picture of the division of a register into fields, as a
588: comment in a program), use the command `edit-picture' to enter Picture
589: mode.
590:
591: In Picture mode, editing is based on the "quarter-plane" model of
592: text, according to which the text characters lie studded on an area that
593: stretches infinitely far to the right and downward. The concept of the
594: end of a line does not exist in this model; the most you can say is
595: where the last nonblank character on the line is found.
596:
597: Of course, Emacs really always considers text as a sequence of
598: characters, and lines really do have ends. But in Picture mode most
599: frequently-used keys are rebound to commands that simulate the
600: quarter-plane model of text. They do this by inserting spaces or by
601: converting tabs to spaces.
602:
603: Most of the basic editing commands of Emacs are redefined by Picture
604: mode to do essentially the same thing but in a quarter-plane way. In
605: addition, Picture mode defines various keys starting with the `C-c'
606: prefix to run special picture editing commands.
607:
608: One of these keys, `C-c C-c', is pretty important. Often a picture
609: is part of a larger file that is usually edited in some other major
610: mode. `M-x edit-picture' records the name of the previous major mode,
611: and then you can use the `C-c C-c' command (`picture-mode-exit') to
612: restore that mode. `C-c C-c' also deletes spaces from the ends of
613: lines, unless given a numeric argument.
614:
615: The commands used in Picture mode all work in other modes (provided
616: the `picture' library is loaded), but are not bound to keys except in
617: Picture mode. Note that the descriptions below talk of moving "one
618: column" and so on, but all the picture mode commands handle numeric
619: arguments as their normal equivalents do.
620:
621: Turning on Picture mode calls the value of the variable
622: `picture-mode-hook' as a function, with no arguments, if that value
623: exists and is non-`nil'.
624:
625: * Menu:
626:
627: * Basic Picture:: Basic concepts and simple commands of Picture Mode.
628: * Insert in Picture:: Controlling direction of cursor motion
629: after "self-inserting" characters.
630: * Tabs in Picture:: Various features for tab stops and indentation.
631: * Rectangles in Picture:: Clearing and superimposing rectangles.
632:
633:
634: File: emacs, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture
635:
636: Basic Editing in Picture Mode
637: =============================
638:
639: Most keys do the same thing in Picture mode that they usually do,
640: but do it in a quarter-plane style. For example, `C-f' is rebound to
641: run `picture-forward-column', which is defined to move point one column
642: to the right, by inserting a space if necessary, so that the actual end
643: of the line makes no difference. `C-b' is rebound to run
644: `picture-backward-column', which always moves point left one column,
645: converting a tab to multiple spaces if necessary. `C-n' and `C-p' are
646: rebound to run `picture-move-down' and `picture-move-up', which can
647: either insert spaces or convert tabs as necessary to make sure that
648: point stays in exactly the same column. `C-e' runs
649: `picture-end-of-line', which moves to after the last nonblank character
650: on the line. There is no need to change `C-a', as the choice of screen
651: model does not affect beginnings of lines.
652:
653: Insertion of text is adapted to the quarter-plane screen model
654: through the use of Overwrite mode (*note Minor Modes::.).
655: Self-inserting characters replace existing text, column by column,
656: rather than pushing existing text to the right. RET runs
657: `picture-newline', which just moves to the beginning of the following
658: line so that new text will replace that line.
659:
660: Deletion and killing of text are replaced with erasure. DEL
661: (`picture-backward-clear-column') replaces the preceding character with
662: a space rather than removing it. `C-d' (`picture-clear-column') does
663: the same thing in a forward direction. `C-k' (`picture-clear-line')
664: really kills the contents of lines, but does not ever remove the
665: newlines from the buffer.
666:
667: To do actual insertion, you must use special commands. `C-o'
668: (`picture-open-line') still creates a blank line, but does so after the
669: current line; it never splits a line. `C-M-o', `split-line', makes
670: sense in Picture mode, so it is not changed. LFD
671: (`picture-duplicate-line') inserts below the current line another line
672: with the same contents.
673:
674: Real deletion can be done with `C-w', or with `C-c C-d' (which is
675: defined as `delete-char', as `C-d' is in other modes), or with one of
676: the picture rectangle commands (*note Rectangles in Picture::.).
677:
678:
679: File: emacs, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
680:
681: Controlling Motion after Insert
682: ===============================
683:
684: Since "self-inserting" characters in Picture mode just overwrite and
685: move point, there is no essential restriction on how point should be
686: moved. Normally point moves right, but you can specify any of the eight
687: orthogonal or diagonal directions for motion after a "self-inserting"
688: character. This is useful for drawing lines in the buffer.
689:
690: `C-c <'
691: Move left after insertion (`picture-movement-left').
692:
693: `C-c >'
694: Move right after insertion (`picture-movement-right').
695:
696: `C-c ^'
697: Move up after insertion (`picture-movement-up').
698:
699: `C-c .'
700: Move down after insertion (`picture-movement-down').
701:
702: `C-c `'
703: Move up and left ("northwest") after insertion
704: (`picture-movement-nw').
705:
706: `C-c ''
707: Move up and right ("northeast") after insertion
708: (`picture-movement-ne').
709:
710: `C-c /'
711: Move down and left ("southwest") after insertion
712: (`picture-movement-sw').
713:
714: `C-c \'
715: Move down and right ("southeast") after insertion
716: (`picture-movement-se').
717:
718: Two motion commands move based on the current Picture insertion
719: direction. The command `C-c C-f' (`picture-motion') moves in the same
720: direction as motion after "insertion" currently does, while `C-c C-b'
721: (`picture-motion-reverse') moves in the opposite direction.
722:
723:
724: File: emacs, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture
725:
726: Picture Mode Tabs
727: =================
728:
729: Two kinds of tab-like action are provided in Picture mode.
730: Context-based tabbing is done with `M-TAB' (`picture-tab-search').
731: With no argument, it moves to a point underneath the next "interesting"
732: character that follows whitespace in the previous nonblank line.
733: "Next" here means "appearing at a horizontal position greater than the
734: one point starts out at". With an argument, as in `C-u M-TAB', this
735: command moves to the next such interesting character in the current
736: line. `M-TAB' does not change the text; it only moves point.
737: "Interesting" characters are defined by the variable
738: `picture-tab-chars', which contains a string whose characters are all
739: considered interesting. Its default value is `"!-~"'.
740:
741: TAB itself runs `picture-tab', which operates based on the current
742: tab stop settings; it is the Picture mode equivalent of
743: `tab-to-tab-stop'. Normally it just moves point, but with a numeric
744: argument it clears the text that it moves over.
745:
746: The context-based and tab-stop-based forms of tabbing are brought
747: together by the command `C-c TAB', `picture-set-tab-stops'. This
748: command sets the tab stops to the positions which `M-TAB' would
749: consider significant in the current line. The use of this command,
750: together with TAB, can get the effect of context-based tabbing. But
751: `M-TAB' is more convenient in the cases where it is sufficient.
752:
753:
754: File: emacs, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
755:
756: Picture Mode Rectangle Commands
757: ===============================
758:
759: Picture mode defines commands for working on rectangular pieces of
760: the text in ways that fit with the quarter-plane model. The standard
761: rectangle commands may also be useful (*note Rectangles::.).
762:
763: `C-c C-k'
764: Clear out the region-rectangle (`picture-clear-rectangle'). With
765: argument, kill it.
766:
767: `C-c C-w R'
768: Similar but save rectangle contents in register R first
769: (`picture-clear-rectangle-to-register').
770:
771: `C-c C-y'
772: Copy last killed rectangle into the buffer by overwriting, with
773: upper left corner at point (`picture-yank-rectangle'). With
774: argument, insert instead.
775:
776: `C-c C-x R'
777: Similar, but use the rectangle in register R
778: (`picture-yank-rectangle-from-register').
779:
780: The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
781: and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
782: standard rectangle commands in that they normally clear the rectangle
783: instead of deleting it; this is analogous with the way `C-d' is changed
784: in Picture mode.
785:
786: However, deletion of rectangles can be useful in Picture mode, so
787: these commands delete the rectangle if given a numeric argument.
788:
789: The Picture mode commands for yanking rectangles differ from the
790: standard ones in overwriting instead of inserting. This is the same
791: way that Picture mode insertion of other text is different from other
792: modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) the
793: rectangle that was most recently killed, while `C-c C-x'
794: (`picture-yank-rectangle-from-register') does likewise for the
795: rectangle found in a specified register.
796:
797:
798: File: emacs, Node: Sending Mail, Next: Rmail, Prev: Picture, Up: Top
799:
800: Sending Mail
801: ************
802:
803: To send a message in Emacs, you start by typing a command (`C-x m')
804: to select and initialize the `*mail*' buffer. Then you edit the text
805: and headers of the message in this buffer, and type another command
806: (`C-c C-c') to send the message.
807:
808: `C-x m'
809: Begin composing a message to send (`mail').
810:
811: `C-x 4 m'
812: Likewise, but display the message in another window
813: (`mail-other-window').
814:
815: `C-c C-c'
816: In Mail mode, send the message and switch to another buffer
817: (`mail-send-and-exit').
818:
819: The command `C-x m' (`mail') selects a buffer named `*mail*' and
820: initializes it with the skeleton of an outgoing message. `C-x 4 m'
821: (`mail-other-window') selects the `*mail*' buffer in a different
822: window, leaving the previous current buffer visible.
823:
824: Because the mail composition buffer is an ordinary Emacs buffer, you
825: can switch to other buffers while in the middle of composing mail, and
826: switch back later (or never). If you use the `C-x m' command again
827: when you have been composing another message but have not sent it, you
828: are asked to confirm before the old message is erased. If you answer
829: `n', the `*mail*' buffer is left selected with its old contents, so you
830: can finish the old message and send it. `C-u C-x m' is another way to
831: do this. Sending the message marks the `*mail*' buffer "unmodified",
832: which avoids the need for confirmation when `C-x m' is next used.
833:
834: If you are composing a message in the `*mail*' buffer and want to
835: send another message before finishing the first, rename the `*mail*'
836: buffer using `M-x rename-buffer' (*note Misc Buffer::.).
837:
838: * Menu:
839:
840: * Format: Mail Format. Format of the mail being composed.
841: * Headers: Mail Headers. Details of allowed mail header fields.
842: * Mode: Mail Mode. Special commands for editing mail being composed.
843:
844:
845: File: emacs, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
846:
847: The Format of the Mail Buffer
848: =============================
849:
850: In addition to the "text" or contents, a message has "header fields"
851: which say who sent it, when, to whom, why, and so on. Some header
852: fields such as the date and sender are created automatically after the
853: message is sent. Others, such as the recipient names, must be
854: specified by you in order to send the message properly.
855:
856: Mail mode provides a few commands to help you edit some header
857: fields, and some are preinitialized in the buffer automatically at
858: times. You can insert or edit any header fields using ordinary editing
859: commands.
860:
861: The line in the buffer that says
862:
863: --text follows this line--
864:
865: is a special delimiter that separates the headers you have specified
866: from the text. Whatever follows this line is the text of the message;
867: the headers precede it. The delimiter line itself does not appear in
868: the message actually sent. The text used for the delimiter line is
869: controlled by the variable `mail-header-separator'.
870:
871: Here is an example of what the headers and text in the `*mail*'
872: buffer might look like.
873:
874: To: rms@mc
875: CC: mly@mc, rg@oz
876: Subject: The Emacs Manual
877: --Text follows this line--
878: Please ignore this message.
879:
880:
881: File: emacs, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
882:
883: Mail Header Fields
884: ==================
885:
886: There are several header fields you can use in the `*mail*' buffer.
887: Each header field starts with a field name at the beginning of a line,
888: terminated by a colon. It does not matter whether you use upper or
889: lower case in the field name. After the colon and optional whitespace
890: comes the contents of the field.
891:
892: `To'
893: This field contains the mailing addresses to which the message is
894: addressed.
895:
896: `Subject'
897: The contents of the `Subject' field should be a piece of text that
898: says what the message is about. The reason `Subject' fields are
899: useful is that most mail-reading programs can provide a summary of
900: messages, listing the subject of each message but not its text.
901:
902: `CC'
903: This field contains additional mailing addresses to send the
904: message to, but whose readers should not regard the message as
905: addressed to them.
906:
907: `BCC'
908: This field contains additional mailing addresses to send the
909: message to, but which should not appear in the header of the
910: message actually sent.
911:
912: `FCC'
913: This field contains the name of one file (in Unix mail file
914: format) to which a copy of the message should be appended when the
915: message is sent.
916:
917: `From'
918: Use the `From' field to say who you are, when the account you are
919: using to send the mail is not your own. The contents of the
920: `From' field should be a valid mailing address, since replies will
921: normally go there.
922:
923: `Reply-To'
924: Use the `Reply-to' field to direct replies to a different address,
925: not your own. There is no difference between `From' and
926: `Reply-to' in their effect on where replies go, but they convey a
927: different meaning to the human who reads the message.
928:
929: If you set the variable `mail-default-reply-to' to a non-`nil'
930: value, then every message you begin to edit will have a `Reply-to'
931: field whose contents are the value of the variable.
932:
933: `In-Reply-To'
934: This field contains a piece of text describing a message you are
935: replying to. Some mail systems can use this information to
936: correlate related pieces of mail. Normally this field is filled
937: in by Rmail when you are replying to a message in Rmail, and you
938: never need to think about it (*note Rmail::.).
939:
940: The `To', `CC', `BCC' and `FCC' fields can appear any number of
941: times, to specify many places to send the message.
942:
943: The `To', `CC', and `BCC' fields can have continuation lines. All
944: the lines starting with whitespace, following the line on which the
945: field starts, are considered part of the field. For example,
946:
947: To: foo@here, this@there,
948: [email protected]
949:
950: If you have a `~/.mailrc' file, Emacs will scan it for mail aliases
951: the first time you try to send mail in an Emacs session. Aliases found
952: in the `To', `CC', and `BCC' fields will be expanded where appropriate.
953:
954: If the variable `mail-archive-file-name' is non-`nil', it should be a
955: string naming a file; every time you start to edit a message to send,
956: an `FCC' field will be put in for that file. Unless you remove the
957: `FCC' field, every message will be written into that file when it is
958: sent.
959:
960:
961: File: emacs, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail
962:
963: Mail Mode
964: =========
965:
966: The major mode used in the `*mail*' buffer is Mail mode, which is
967: much like Text mode except that various special commands are provided on
968: the `C-c' prefix. These commands all have to do specifically with
969: editing or sending the message.
970:
971: `C-c C-s'
972: Send the message, and leave the `*mail*' buffer selected
973: (`mail-send').
974:
975: `C-c C-c'
976: Send the message, and select some other buffer
977: (`mail-send-and-exit').
978:
979: `C-c C-f C-t'
980: Move to the `To' header field, creating one if there is none
981: (`mail-to').
982:
983: `C-c C-f C-s'
984: Move to the `Subject' header field, creating one if there is none
985: (`mail-subject').
986:
987: `C-c C-f C-c'
988: Move to the `CC' header field, creating one if there is none
989: (`mail-cc').
990:
991: `C-c C-w'
992: Insert the file `~/.signature' at the end of the message text
993: (`mail-signature').
994:
995: `C-c C-y'
996: Yank the selected message from Rmail (`mail-yank-original'). This
997: command does nothing unless your command to start sending a
998: message was issued with Rmail.
999:
1000: `C-c C-q'
1001: Fill all paragraphs of yanked old messages, each individually
1002: (`mail-fill-yanked-message').
1003:
1004: There are two ways to send the message. `C-c C-s' (`mail-send')
1005: sends the message and marks the `*mail*' buffer unmodified, but leaves
1006: that buffer selected so that you can modify the message (perhaps with
1007: new recipients) and send it again. `C-c C-c' (`mail-send-and-exit')
1008: sends and then deletes the window (if there is another window) or
1009: switches to another buffer. It puts the `*mail*' buffer at the lowest
1010: priority for automatic reselection, since you are finished with using
1011: it. This is the usual way to send the message.
1012:
1013: Mail mode provides some other special commands that are useful for
1014: editing the headers and text of the message before you send it. There
1015: are three commands defined to move point to particular header fields,
1016: all based on the prefix `C-c C-f' (`C-f' is for "field"). They are
1017: `C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
1018: (`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
1019: for the `CC' field. These fields have special motion commands because
1020: they are the most common fields for the user to want to edit.
1021:
1022: `C-c C-w' (`mail-signature') adds a standard piece text at the end
1023: of the message to say more about who you are. The text comes from the
1024: file `.signature' in your home directory.
1025:
1026: When mail sending is invoked from the Rmail mail reader using an
1027: Rmail command, `C-c C-y' can be used inside the `*mail*' buffer to
1028: insert the text of the message you are replying to. Normally it
1029: indents each line of that message four spaces and eliminates most
1030: header fields. A numeric argument specifies the number of spaces to
1031: indent. An argument of just `C-u' says not to indent at all and not to
1032: eliminate anything. `C-c C-y' always uses the current message from the
1033: `RMAIL' buffer, so you can insert several old messages by selecting one
1034: in `RMAIL', switching to `*mail*' and yanking it, then switching back to
1035: `RMAIL' to select another.
1036:
1037: After using `C-c C-y', you can type the command `C-c C-q'
1038: (`mail-fill-yanked-message') to fill the paragraphs of the yanked old
1039: message or messages. One use of `C-c C-q' fills all such paragraphs,
1040: each one separately.
1041:
1042: Turning on Mail mode (which `C-x m' does automatically) calls the
1043: value of `text-mode-hook', if it is not void or `nil', and then calls
1044: the value of `mail-mode-hook' if that is not void or `nil'. Aside from
1045: these, the `mail' command runs `mail-setup-hook' whenever it
1046: initializes the `*mail*' buffer for editing a message.
1047:
1048:
1049: File: emacs, Node: Rmail, Next: Recursive Edit, Prev: Sending Mail, Up: Top
1050:
1051: Reading Mail with Rmail
1052: ***********************
1053:
1054: Rmail is an Emacs subsystem for reading and disposing of mail that
1055: you receive. Rmail stores mail messages in files called "Rmail files".
1056: Reading the message in an Rmail file is done in a special major mode,
1057: Rmail mode, which redefines most letters to run commands for managing
1058: mail. To enter Rmail, type `M-x rmail'. This reads your primary mail
1059: file, merges new mail in from your inboxes, displays the first new
1060: message, and lets you begin reading.
1061:
1062: Using Rmail in the simplest fashion, you have one Rmail file,
1063: `~/RMAIL', in which all of your mail is saved. It is called your
1064: "primary mail file". In more sophisticated usage, you can copy
1065: messages into other Rmail files and then edit those files with Rmail.
1066:
1067: Rmail displays only one message at a time. It is called the "current
1068: message". Rmail mode's special commands can do such things as move to
1069: another message, delete the message, copy the message into another
1070: file, or send a reply.
1071:
1072: Within the Rmail file, messages are arranged sequentially in order
1073: of receipt. They are also assigned consecutive integers as their
1074: "message numbers". The number of the current message is displayed in
1075: Rmail's mode line, followed by the total number of messages in the
1076: file. You can move to a message by specifying its message number using
1077: the `j' key (*note Rmail Motion::.).
1078:
1079: Following the usual conventions of Emacs, changes in an Rmail file
1080: become permanent only when the file is saved. You can do this with `s'
1081: (`rmail-save'), which also expunges deleted messages from the file
1082: first (*note Rmail Deletion::.). To save the file without expunging,
1083: use `C-x C-s'. Rmail saves the Rmail file spontaneously when moving new
1084: mail from an inbox file (*note Rmail Inbox::.).
1085:
1086: You can exit Rmail with `q' (`rmail-quit'); this expunges and saves
1087: the Rmail file and then switches to another buffer. But there is no
1088: need to `exit' formally. If you switch from Rmail to editing in other
1089: buffers, and never happen to switch back, you have exited. Just make
1090: sure to save the Rmail file eventually (like any other file you have
1091: changed). `C-x s' is a good enough way to do this (*note Saving::.).
1092:
1093: * Menu:
1094:
1095: * Scroll: Rmail Scrolling. Scrolling through a message.
1096: * Motion: Rmail Motion. Moving to another message.
1097: * Deletion: Rmail Deletion. Deleting and expunging messages.
1098: * Inbox: Rmail Inbox. How mail gets into the Rmail file.
1099: * Files: Rmail Files. Using multiple Rmail files.
1100: * Output: Rmail Output. Copying message out to files.
1101: * Labels: Rmail Labels. Classifying messages by labeling them.
1102: * Summary: Rmail Summary. Summaries show brief info on many messages.
1103: * Reply: Rmail Reply. Sending replies to messages you are viewing.
1104: * Editing: Rmail Editing. Editing message text and headers in Rmail.
1105: * Digest: Rmail Digest. Extracting the messages from a digest message.
1106:
1107:
1108: File: emacs, Node: Rmail Scrolling, Next: Rmail Motion, Prev: Rmail, Up: Rmail
1109:
1110: Scrolling Within a Message
1111: ==========================
1112:
1113: When Rmail displays a message that does not fit on the screen, it is
1114: necessary to scroll through it. This could be done with `C-v', `M-v'
1115: and `M-<', but in Rmail scrolling is so frequent that it deserves to be
1116: easier to type.
1117:
1118: `SPC'
1119: Scroll forward (`scroll-up').
1120:
1121: `DEL'
1122: Scroll backward (`scroll-down').
1123:
1124: `.'
1125: Scroll to start of message (`rmail-beginning-of-message').
1126:
1127: Since the most common thing to do while reading a message is to
1128: scroll through it by screenfuls, Rmail makes SPC and DEL synonyms of
1129: `C-v' (`scroll-up') and `M-v' (`scroll-down').
1130:
1131: The command `.' (`rmail-beginning-of-message') scrolls back to the
1132: beginning of the selected message. This is not quite the same as `M-<':
1133: for one thing, it does not set the mark; for another, it resets the
1134: buffer boundaries to the current message if you have changed them.
1135:
1136:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.