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: Minor Modes, Next: Variables, Up: Customization
38 Minor modes are options which you can use or not. For example, Auto
39 Fill mode is a minor mode in which <SPC> breaks lines between words as
40 you type. All the minor modes are independent of each other and of the
41 selected major mode. Most minor modes inform you in the mode line when
42 they are on; for example, `Fill' in the mode line means that Auto Fill
45 Append `-mode' to the name of a minor mode to get the name of a
46 command function that turns the mode on or off. Thus, the command to
47 enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
48 commands are usually invoked with `M-x', but you can bind keys to them
49 if you wish. With no argument, the function turns the mode on if it was
50 off and off if it was on. This is known as "toggling". A positive
51 argument always turns the mode on, and an explicit zero argument or a
52 negative argument always turns it off.
54 Auto Fill mode allows you to enter filled text without breaking lines
55 explicitly. Emacs inserts newlines as necessary to prevent lines from
56 becoming too long. *Note Filling::.
58 Overwrite mode causes ordinary printing characters to replace
59 existing text instead of moving it to the right. For example, if point
60 is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
61 mode, it changes to `FOOGAR', instead of `FOOGBAR'.
63 Abbrev mode allows you to define abbreviations that automatically
64 expand as you type them. For example, `amd' might expand to `abbrev
65 mode'. *Note Abbrevs::, for full information.
68 File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
73 A "variable" is a Lisp symbol which has a value. Variable names can
74 contain any characters, but by convention they are words separated by
75 hyphens. A variable can also have a documentation string, which
76 describes what kind of value it should have and how the value will be
79 Lisp allows any variable to have any kind of value, but most
80 variables that Emacs uses require a value of a certain type. Often the
81 value has to be a string or a number. Sometimes we say that a certain
82 feature is turned on if a variable is "non-`nil'," meaning that if the
83 variable's value is `nil', the feature is off, but the feature is on
84 for any other value. The conventional value to turn on the
85 feature--since you have to pick one particular value when you set the
88 Emacs uses many Lisp variables for internal recordkeeping, as any
89 Lisp program must, but the most interesting variables for you are the
90 ones that exist for the sake of customization. Emacs does not
91 (usually) change the values of these variables; instead, you set the
92 values, and thereby alter and control the behavior of certain Emacs
93 commands. These variables are called "options". Most options are
94 documented in this manual and appear in the Variable Index (*note
97 One example of a variable which is an option is `fill-column', which
98 specifies the position of the right margin (as a number of characters
99 from the left margin) to be used by the fill commands (*note Filling::).
103 * Examining:: Examining or setting one variable's value.
104 * Easy Customization:: Convenient and easy customization of variables.
105 * Edit Options:: Examining or editing list of all variables' values.
106 * Locals:: Per-buffer values of variables.
107 * File Variables:: How files can specify variable values.
110 File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
112 Examining and Setting Variables
113 -------------------------------
116 `M-x describe-variable'
117 Print the value and documentation of a variable.
120 Change the value of a variable.
122 To examine the value of a single variable, use `C-h v'
123 (`describe-variable'), which reads a variable name using the
124 minibuffer, with completion. It prints both the value and the
125 documentation of the variable.
127 C-h v fill-column <RET>
129 prints something like:
131 fill-column's value is 75
134 *Column beyond which automatic line-wrapping should happen.
135 Automatically becomes local when set in any fashion.
137 The star at the beginning of the documentation indicates that this
138 variable is an option. `C-h v' is not restricted to options; it allows
141 If you know which option you want to set, you can use `M-x
142 set-variable' to set it. This prompts for the variable name in the
143 minibuffer (with completion), and then prompts for a Lisp expression
144 for the new value using the minibuffer a second time. For example,
146 M-x set-variable <RET> fill-column <RET> 75 <RET>
148 sets `fill-column' to 75, as if you had executed the Lisp expression
149 `(setq fill-column 75)'.
151 Setting variables in this way, like all means of customizing Emacs
152 except where explicitly stated, affects only the current Emacs session.
155 File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
157 Easy Customization Interface
158 ----------------------------
160 A convenient way to find the user option variables that you want to
161 change, and then change them, is with `M-x customize'. This command
162 creates a "customization buffer" with which you can browse through the
163 Emacs user options in a logically organized structure, then edit and
164 set their values. You can also use the customization buffer to save
165 settings permanently. (Not all Emacs user options are included in this
166 structure as of yet, but we are adding the rest.)
170 * Groups: Customization Groups.
171 How options are classified in a structure.
172 * Changing an Option:: How to edit a value and set an option.
173 * Face Customization:: How to edit the attributes of a face.
174 * Specific Customization:: Making a customization buffer for specific
175 options, faces, or groups.
178 File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
183 For customization purposes, user options are organized into "groups"
184 to help you find them. Groups are collected into bigger groups, all
185 the way up to a master group called `Emacs'.
187 `M-x customize' creates a customization buffer that shows the
188 top-level `Emacs' group and the second-level groups immediately under
189 it. It looks like this, in part:
191 /- Emacs group: ---------------------------------------------------\
192 [State]: visible group members are all at standard settings.
193 Customization of the One True Editor.
197 Basic text editing facilities.
199 [Open] External group
200 Interfacing to external utilities.
202 MORE SECOND-LEVEL GROUPS
204 \- Emacs group end ------------------------------------------------/
206 This says that the buffer displays the contents of the `Emacs' group.
207 The other groups are listed because they are its contents. But they
208 are listed differently, without indentation and dashes, because _their_
209 contents are not included. Each group has a single-line documentation
210 string; the `Emacs' group also has a `[State]' line.
212 Most of the text in the customization buffer is read-only, but it
213 typically includes some "editable fields" that you can edit. There are
214 also "active fields"; this means a field that does something when you
215 "invoke" it. To invoke an active field, either click on it with
216 `Mouse-1', or move point to it and type <RET>.
218 For example, the phrase `[Open]' that appears in a second-level
219 group is an active field. Invoking the `[Open]' field for a group
220 opens up a new customization buffer, which shows that group and its
221 contents. This field is a kind of hypertext link to another group.
223 The `Emacs' group does not include any user options itself, but
224 other groups do. By examining various groups, you will eventually find
225 the options and faces that belong to the feature you are interested in
226 customizing. Then you can use the customization buffer to set them.
228 You can view the structure of customization groups on a larger scale
229 with `M-x customize-browse'. This command creates a special kind of
230 customization buffer which shows only the names of the groups (and
231 options and faces), and their structure.
233 In this buffer, you can show the contents of a group by invoking
234 `[+]'. When the group contents are visible, this button changes to
235 `[-]'; invoking that hides the group contents.
237 Each group, option or face name in this buffer has an active field
238 which says `[Group]', `[Option]' or `[Face]'. Invoking that active
239 field creates an ordinary customization buffer showing just that group
240 and its contents, just that option, or just that face. This is the way
244 File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
249 Here is an example of what a user option looks like in the
250 customization buffer:
252 Kill Ring Max: [Hide] 30
253 [State]: this option is unchanged from its standard setting.
254 Maximum length of kill ring before oldest elements are thrown away.
256 The text following `[Hide]', `30' in this case, indicates the
257 current value of the option. If you see `[Show]' instead of `[Hide]',
258 it means that the value is hidden; the customization buffer initially
259 hides values that take up several lines. Invoke `[Show]' to show the
262 The line after the option name indicates the "customization state"
263 of the option: in the example above, it says you have not changed the
264 option yet. The word `[State]' at the beginning of this line is
265 active; you can get a menu of various operations by invoking it with
266 `Mouse-1' or <RET>. These operations are essential for customizing the
269 The line after the `[State]' line displays the beginning of the
270 option's documentation string. If there are more lines of
271 documentation, this line ends with `[More]'; invoke this to show the
272 full documentation string.
274 To enter a new value for `Kill Ring Max', move point to the value
275 and edit it textually. For example, you can type `M-d', then insert
278 When you begin to alter the text, you will see the `[State]' line
279 change to say that you have edited the value:
281 [State]: you have edited the value as text, but not set the option.
283 Editing the value does not actually set the option variable. To do
284 that, you must "set" the option. To do this, invoke the word `[State]'
285 and choose `Set for Current Session'.
287 The state of the option changes visibly when you set it:
289 [State]: you have set this option, but not saved it for future sessions.
291 You don't have to worry about specifying a value that is not valid;
292 setting the option checks for validity and will not really install an
295 While editing a value or field that is a file name, directory name,
296 command name, or anything else for which completion is defined, you can
297 type `M-<TAB>' (`widget-complete') to do completion.
299 Some options have a small fixed set of possible legitimate values.
300 These options don't let you edit the value textually. Instead, an
301 active field `[Value Menu]' appears before the value; invoke this field
302 to edit the value. For a boolean "on or off" value, the active field
303 says `[Toggle]', and it changes to the other value. `[Value Menu]' and
304 `[Toggle]' edit the buffer; the changes take effect when you use the
305 `Set for Current Session' operation.
307 Some options have values with complex structure. For example, the
308 value of `load-path' is a list of directories. Here is how it appears
309 in the customization buffer:
312 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
313 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
314 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
315 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
316 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
317 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
319 [State]: this item has been changed outside the customization buffer.
320 List of directories to search for files to load....
322 Each directory in the list appears on a separate line, and each line has
323 several editable or active fields.
325 You can edit any of the directory names. To delete a directory from
326 the list, invoke `[DEL]' on that line. To insert a new directory in
327 the list, invoke `[INS]' at the point where you want to insert it.
329 You can also invoke `[Current dir?]' to switch between including a
330 specific named directory in the path, and including `nil' in the path.
331 (`nil' in a search path means "try the current directory.")
333 Two special commands, <TAB> and `S-<TAB>', are useful for moving
334 through the customization buffer. <TAB> (`widget-forward') moves
335 forward to the next active or editable field; `S-<TAB>'
336 (`widget-backward') moves backward to the previous active or editable
339 Typing <RET> on an editable field also moves forward, just like
340 <TAB>. The reason for this is that people have a tendency to type
341 <RET> when they are finished editing a field. If you have occasion to
342 insert a newline in an editable field, use `C-o' or `C-q C-j',
344 Setting the option changes its value in the current Emacs session;
345 "saving" the value changes it for future sessions as well. This works
346 by writing code into your `~/.emacs' file so as to set the option
347 variable again each time you start Emacs. To save the option, invoke
348 `[State]' and select the `Save for Future Sessions' operation.
350 You can also restore the option to its standard value by invoking
351 `[State]' and selecting the `Reset' operation. There are actually
352 three reset operations:
355 If you have made some modifications and not yet set the option,
356 this restores the text in the customization buffer to match the
360 This restores the value of the option to the last saved value, and
361 updates the text accordingly.
363 `Reset to Standard Settings'
364 This sets the option to its standard value, and updates the text
365 accordingly. This also eliminates any saved value for the option,
366 so that you will get the standard value in future Emacs sessions.
368 The state of a group indicates whether anything in that group has
369 been edited, set or saved. You can select `Set for Current Session',
370 `Save for Future Sessions' and the various kinds of `Reset' operation
371 for the group; these operations on the group apply to all options in
372 the group and its subgroups.
374 Near the top of the customization buffer there are two lines
375 containing several active fields:
377 [Set] [Save] [Reset] [Done]
379 Invoking `[Done]' buries this customization buffer. Each of the other
380 fields performs an operation--set, save or reset--on each of the items
381 in the buffer that could meaningfully be set, saved or reset.
384 File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
389 In addition to user options, some customization groups also include
390 faces. When you show the contents of a group, both the user options and
391 the faces in the group appear in the customization buffer. Here is an
392 example of how a face looks:
394 Custom Changed Face: (sample)
395 [State]: this face is unchanged from its standard setting.
396 Face used when the customize item has been changed.
397 Parent groups: [Custom Magic Faces]
398 Attributes: [ ] Bold: [Toggle] off (nil)
399 [ ] Italic: [Toggle] off (nil)
400 [ ] Underline: [Toggle] off (nil)
401 [ ] Foreground: white (sample)
402 [ ] Background: blue (sample)
403 [ ] Inverse: [Toggle] off (nil)
409 Each face attribute has its own line. The `[X]' field before the
410 attribute name indicates whether the attribute is "enabled"; `X' means
411 that it is. You can enable or disable the attribute by invoking that
412 field. When the attribute is enabled, you can change the attribute
413 value in the usual ways.
415 Setting, saving and resetting a face work like the same operations
416 for options (*note Changing an Option::).
418 A face can specify different appearances for different types of
419 display. For example, a face can make text red on a color display, but
420 use a bold font on a monochrome display. To specify multiple
421 appearances for a face, select `Show Display Types' in the menu you get
422 from invoking `[State]'.
425 File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
427 Customizing Specific Items
428 ..........................
430 Instead of finding the options you want to change by moving down
431 through the structure of groups, you can specify the particular option,
432 face or group that you want to customize.
434 `M-x customize-option <RET> OPTION <RET>'
435 Set up a customization buffer with just one option, OPTION.
437 `M-x customize-face <RET> FACE <RET>'
438 Set up a customization buffer with just one face, FACE.
440 `M-x customize-group <RET> GROUP <RET>'
441 Set up a customization buffer with just one group, GROUP.
443 `M-x customize-apropos <RET> REGEXP <RET>'
444 Set up a customization buffer with all the options, faces and
445 groups that match REGEXP.
447 `M-x customize-saved'
448 Set up a customization buffer containing all options and faces
449 that you have saved with customization buffers.
451 `M-x customize-customized'
452 Set up a customization buffer containing all options and faces
453 that you have customized but not saved.
455 If you want to alter a particular user option variable with the
456 customization buffer, and you know its name, you can use the command
457 `M-x customize-option' and specify the option name. This sets up the
458 customization buffer with just one option--the one that you asked for.
459 Editing, setting and saving the value work as described above, but only
460 for the specified option.
462 Likewise, you can modify a specific face, chosen by name, using `M-x
465 You can also set up the customization buffer with a specific group,
466 using `M-x customize-group'. The immediate contents of the chosen
467 group, including option variables, faces, and other groups, all appear
468 as well. However, these subgroups' own contents start out hidden. You
469 can show their contents in the usual way, by invoking `[Show]'.
471 To control more precisely what to customize, you can use `M-x
472 customize-apropos'. You specify a regular expression as argument; then
473 all options, faces and groups whose names match this regular expression
474 are set up in the customization buffer. If you specify an empty regular
475 expression, this includes _all_ groups, options and faces in the
476 customization buffer (but that takes a long time).
478 If you change option values and then decide the change was a mistake,
479 you can use two special commands to revisit your previous changes. Use
480 `customize-saved' to look at the options and faces that you have saved.
481 Use `M-x customize-customized' to look at the options and faces that
482 you have set but not saved.
485 File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
487 Editing Variable Values
488 -----------------------
491 Display a buffer listing names, values, and documentation of all
495 Change option values by editing a list of options.
497 `M-x list-options' displays a list of all Emacs option variables in
498 an Emacs buffer named `*List Options*'. Each option is shown with its
499 documentation and its current value. Here is what a portion of it might
503 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
504 *List of directories to search programs to run in subprocesses.
505 Each element is a string (directory name)
506 or nil (try the default directory).
510 *Column beyond which automatic line-wrapping should happen.
511 Automatically becomes local when set in any fashion.
514 `M-x edit-options' goes one step further and immediately selects the
515 `*List Options*' buffer; this buffer uses the major mode Options mode,
516 which provides commands that allow you to point at an option and change
520 Set the variable point is in or near to a new value read using the
524 Toggle the variable point is in or near: if the value was `nil',
525 it becomes `t'; otherwise it becomes `nil'.
528 Set the variable point is in or near to `t'.
531 Set the variable point is in or near to `nil'.
535 Move to the next or previous variable.
538 File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
543 `M-x make-local-variable'
544 Make a variable have a local value in the current buffer.
546 `M-x kill-local-variable'
547 Make a variable use its global value in the current buffer.
549 `M-x make-variable-buffer-local'
550 Mark a variable so that setting it will make it local to the
551 buffer that is current at that time.
553 You can make any variable "local" to a specific Emacs buffer. This
554 means that the variable's value in that buffer is independent of its
555 value in other buffers. A few variables are always local in every
556 buffer. All other Emacs variables have a "global" value which is in
557 effect in all buffers that have not made the variable local.
559 Major modes always make the variables they set local to the buffer.
560 This is why changing major modes in one buffer has no effect on other
563 `M-x make-local-variable' reads the name of a variable and makes it
564 local to the current buffer. Further changes in this buffer will not
565 affect others, and changes in the global value will not affect this
568 `M-x make-variable-buffer-local' reads the name of a variable and
569 changes the future behavior of the variable so that it automatically
570 becomes local when it is set. More precisely, once you have marked a
571 variable in this way, the usual ways of setting the variable will
572 automatically invoke `make-local-variable' first. We call such
573 variables "per-buffer" variables.
575 Some important variables have been marked per-buffer already. They
576 include `abbrev-mode', `auto-fill-function', `case-fold-search',
577 `comment-column', `ctl-arrow', `fill-column', `fill-prefix',
578 `indent-tabs-mode', `left-margin',
579 `mode-line-format', `overwrite-mode', `selective-display-ellipses',
580 `selective-display', `tab-width', and `truncate-lines'. Some other
581 variables are always local in every buffer, but they are used for
584 Note: the variable `auto-fill-function' was formerly named
587 If you want a variable to cease to be local to the current buffer,
588 call `M-x kill-local-variable' and provide the name of a variable to
589 the prompt. The global value of the variable is again in effect in
590 this buffer. Setting the major mode kills all the local variables of
593 To set the global value of a variable, regardless of whether the
594 variable has a local value in the current buffer, you can use the Lisp
595 function `setq-default'. It works like `setq'. If there is a local
596 value in the current buffer, the local value is not affected by
597 `setq-default'; thus, the new global value may not be visible until you
598 switch to another buffer, as in the case of:
600 (setq-default fill-column 75)
602 `setq-default' is the only way to set the global value of a variable
603 that has been marked with `make-variable-buffer-local'.
605 Programs can look at a variable's default value with `default-value'.
606 This function takes a symbol as an argument and returns its default
607 value. The argument is evaluated; usually you must quote it
608 explicitly, as in the case of:
610 (default-value 'fill-column)
613 File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables
615 Local Variables in Files
616 ------------------------
618 A file can contain a "local variables list", which specifies the
619 values to use for certain Emacs variables when that file is edited.
620 Visiting the file checks for a local variables list and makes each
621 variable in the list local to the buffer in which the file is visited,
622 with the value specified in the file.
624 A local variables list goes near the end of the file, in the last
625 page. (It is often best to put it on a page by itself.) The local
626 variables list starts with a line containing the string `Local
627 Variables:', and ends with a line containing the string `End:'. In
628 between come the variable names and values, one set per line, as
629 `VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
632 The line which starts the local variables list does not have to say
633 just `Local Variables:'. If there is other text before `Local
634 Variables:', that text is called the "prefix", and if there is other
635 text after, that is called the "suffix". If a prefix or suffix are
636 present, each entry in the local variables list should have the prefix
637 before it and the suffix after it. This includes the `End:' line. The
638 prefix and suffix are included to disguise the local variables list as
639 a comment so the compiler or text formatter will ignore it. If you do
640 not need to disguise the local variables list as a comment in this way,
641 there is no need to include a prefix or a suffix.
643 Two "variable" names are special in a local variables list: a value
644 for the variable `mode' sets the major mode, and a value for the
645 variable `eval' is simply evaluated as an expression and the value is
646 ignored. These are not real variables; setting them in any other
647 context does not have the same effect. If `mode' is used in a local
648 variables list, it should be the first entry in the list.
650 Here is an example of a local variables list:
651 ;;; Local Variables: ***
653 ;;; comment-column:0 ***
654 ;;; comment-start: ";;; " ***
655 ;;; comment-end:"***" ***
658 Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
659 that comments in the file begin with and end with the same strings.
660 Presumably the file contains code in a language which is enough like
661 Lisp for Lisp mode to be useful but in which comments start and end
662 differently. The prefix and suffix are used in the local variables
663 list to make the list look like several lines of comments when the
664 compiler or interpreter for that language reads the file.
666 The start of the local variables list must be no more than 3000
667 characters from the end of the file, and must be in the last page if the
668 file is divided into pages. Otherwise, Emacs will not notice it is
669 there. The purpose is twofold: a stray `Local Variables:' not in the
670 last page does not confuse Emacs, and Emacs never needs to search a
671 long file that contains no page markers and has no local variables list.
673 You may be tempted to turn on Auto Fill mode with a local variable
674 list. That is inappropriate. Whether you use Auto Fill mode or not is
675 a matter of personal taste, not a matter of the contents of particular
676 files. If you want to use Auto Fill, set up major mode hooks with your
677 `.emacs' file to turn it on (when appropriate) for you alone (*note
678 Init File::). Don't try to use a local variable list that would impose
679 your taste on everyone working with the file.
681 XEmacs allows you to specify local variables in the first line of a
682 file, in addition to specifying them in the `Local Variables' section
683 at the end of a file.
685 If the first line of a file contains two occurrences of ``-*-'',
686 XEmacs uses the information between them to determine what the major
687 mode and variable settings should be. For example, these are all legal:
689 ;;; -*- mode: emacs-lisp -*-
690 ;;; -*- mode: postscript; version-control: never -*-
691 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
693 For historical reasons, the syntax ``-*- modename -*-'' is allowed
694 as well; for example, you can use:
696 ;;; -*- emacs-lisp -*-
698 The variable `enable-local-variables' controls the use of local
699 variables lists in files you visit. The value can be `t', `nil', or
700 something else. A value of `t' means local variables lists are obeyed;
701 `nil' means they are ignored; anything else means query.
703 The command `M-x normal-mode' always obeys local variables lists and
704 ignores this variable.
707 File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization
712 A "keyboard macro" is a command defined by the user to abbreviate a
713 sequence of keys. For example, if you discover that you are about to
714 type `C-n C-d' forty times, you can speed your work by defining a
715 keyboard macro to invoke `C-n C-d' and calling it with a repeat count
719 Start defining a keyboard macro (`start-kbd-macro').
722 End the definition of a keyboard macro (`end-kbd-macro').
725 Execute the most recent keyboard macro (`call-last-kbd-macro').
728 Re-execute last keyboard macro, then add more keys to its
732 When this point is reached during macro execution, ask for
733 confirmation (`kbd-macro-query').
735 `M-x name-last-kbd-macro'
736 Give a command name (for the duration of the session) to the most
737 recently defined keyboard macro.
739 `M-x insert-kbd-macro'
740 Insert in the buffer a keyboard macro's definition, as Lisp code.
742 Keyboard macros differ from other Emacs commands in that they are
743 written in the Emacs command language rather than in Lisp. This makes
744 it easier for the novice to write them and makes them more convenient as
745 temporary hacks. However, the Emacs command language is not powerful
746 enough as a programming language to be useful for writing anything
747 general or complex. For such things, Lisp must be used.
749 You define a keyboard macro by executing the commands which are its
750 definition. Put differently, as you are defining a keyboard macro, the
751 definition is being executed for the first time. This way, you see
752 what the effects of your commands are, and don't have to figure them
753 out in your head. When you are finished, the keyboard macro is defined
754 and also has been executed once. You can then execute the same set of
755 commands again by invoking the macro.
759 * Basic Kbd Macro:: Defining and running keyboard macros.
760 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
761 * Kbd Macro Query:: Keyboard macros that do different things each use.
764 File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
769 To start defining a keyboard macro, type `C-x ('
770 (`start-kbd-macro'). From then on, anything you type continues to be
771 executed, but also becomes part of the definition of the macro. `Def'
772 appears in the mode line to remind you of what is going on. When you
773 are finished, the `C-x )' command (`end-kbd-macro') terminates the
774 definition, without becoming part of it.
780 defines a macro to move forward a word and then insert `foo'.
782 You can give `C-x )' a repeat count as an argument, in which case it
783 repeats the macro that many times right after defining it, but defining
784 the macro counts as the first repetition (since it is executed as you
785 define it). If you give `C-x )' an argument of 4, it executes the
786 macro immediately 3 additional times. An argument of zero to `C-x e'
787 or `C-x )' means repeat the macro indefinitely (until it gets an error
790 Once you have defined a macro, you can invoke it again with the `C-x
791 e' command (`call-last-kbd-macro'). You can give the command a repeat
792 count numeric argument to execute the macro many times.
794 To repeat an operation at regularly spaced places in the text,
795 define a macro and include as part of the macro the commands to move to
796 the next place you want to use it. For example, if you want to change
797 each line, you should position point at the start of a line, and define
798 a macro to change that line and leave point at the start of the next
799 line. Repeating the macro will then operate on successive lines.
801 After you have terminated the definition of a keyboard macro, you
802 can add to the end of its definition by typing `C-u C-x ('. This is
803 equivalent to plain `C-x (' followed by retyping the whole definition
804 so far. As a consequence it re-executes the macro as previously
808 File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
810 Naming and Saving Keyboard Macros
811 ---------------------------------
813 To save a keyboard macro for longer than until you define the next
814 one, you must give it a name using `M-x name-last-kbd-macro'. This
815 reads a name as an argument using the minibuffer and defines that name
816 to execute the macro. The macro name is a Lisp symbol, and defining it
817 in this way makes it a valid command name for calling with `M-x' or for
818 binding a key to with `global-set-key' (*note Keymaps::). If you
819 specify a name that has a prior definition other than another keyboard
820 macro, Emacs prints an error message and nothing is changed.
822 Once a macro has a command name, you can save its definition in a
823 file. You can then use it in another editing session. First visit the
824 file you want to save the definition in. Then use the command:
826 M-x insert-kbd-macro <RET> MACRONAME <RET>
828 This inserts some Lisp code that, when executed later, will define the
829 same macro with the same definition it has now. You need not
830 understand Lisp code to do this, because `insert-kbd-macro' writes the
831 Lisp code for you. Then save the file. You can load the file with
832 `load-file' (*note Lisp Libraries::). If the file you save in is your
833 initialization file `~/.emacs' (*note Init File::), then the macro will
834 be defined each time you run Emacs.
836 If you give `insert-kbd-macro' a prefix argument, it creates
837 additional Lisp code to record the keys (if any) that you have bound to
838 the keyboard macro, so that the macro is reassigned the same keys when
842 File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
844 Executing Macros With Variations
845 --------------------------------
847 You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
848 that of `query-replace'. The macro asks you each time whether to make
849 a change. When you are defining the macro, type `C-x q' at the point
850 where you want the query to occur. During macro definition, the `C-x
851 q' does nothing, but when you invoke the macro, `C-x q' reads a
852 character from the terminal to decide whether to continue.
854 The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
855 `C-l', and `C-r'. Any other character terminates execution of the
856 keyboard macro and is then read as a command. <SPC> means to continue.
857 <DEL> means to skip the remainder of this repetition of the macro,
858 starting again from the beginning in the next repetition. `C-d' means
859 to skip the remainder of this repetition and cancel further repetition.
860 `C-l' redraws the frame and asks you again for a character to specify
861 what to do. `C-r' enters a recursive editing level, in which you can
862 perform editing that is not part of the macro. When you exit the
863 recursive edit using `C-M-c', you are asked again how to continue with
864 the keyboard macro. If you type a <SPC> at this time, the rest of the
865 macro definition is executed. It is up to you to leave point and the
866 text in a state such that the rest of the macro will do what you want.
868 `C-u C-x q', which is `C-x q' with a numeric argument, performs a
869 different function. It enters a recursive edit reading input from the
870 keyboard, both when you type it during the definition of the macro and
871 when it is executed from the macro. During definition, the editing you
872 do inside the recursive edit does not become part of the macro. During
873 macro execution, the recursive edit gives you a chance to do some
874 particularized editing. *Note Recursive Edit::.
877 File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
879 Customizing Key Bindings
880 ========================
882 This section deals with the "keymaps" that define the bindings
883 between keys and functions, and shows how you can customize these
886 A command is a Lisp function whose definition provides for
887 interactive use. Like every Lisp function, a command has a function
888 name, which is a Lisp symbol whose name usually consists of lower case
893 * Keymaps:: Definition of the keymap data structure.
894 Names of Emacs's standard keymaps.
895 * Rebinding:: How to redefine one key's meaning conveniently.
896 * Disabling:: Disabling a command means confirmation is required
897 before it can be executed. This is done to protect
898 beginners from surprises.
901 File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
906 The bindings between characters and command functions are recorded in
907 data structures called "keymaps". Emacs has many of these. One, the
908 "global" keymap, defines the meanings of the single-character keys that
909 are defined regardless of major mode. It is the value of the variable
912 Each major mode has another keymap, its "local keymap", which
913 contains overriding definitions for the single-character keys that are
914 redefined in that mode. Each buffer records which local keymap is
915 installed for it at any time, and the current buffer's local keymap is
916 the only one that directly affects command execution. The local keymaps
917 for Lisp mode, C mode, and many other major modes always exist even when
918 not in use. They are the values of the variables `lisp-mode-map',
919 `c-mode-map', and so on. For less frequently used major modes, the
920 local keymap is sometimes constructed only when the mode is used for the
921 first time in a session, to save space.
923 There are local keymaps for the minibuffer, too; they contain various
924 completion and exit commands.
926 * `minibuffer-local-map' is used for ordinary input (no completion).
928 * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
929 like <RET>. This is used mainly for Mocklisp compatibility.
931 * `minibuffer-local-completion-map' is for permissive completion.
933 * `minibuffer-local-must-match-map' is for strict completion and for
936 * `repeat-complex-command-map' is for use in `C-x <ESC>'.
938 * `isearch-mode-map' contains the bindings of the special keys which
939 are bound in the pseudo-mode entered with `C-s' and `C-r'.
941 Finally, each prefix key has a keymap which defines the key sequences
942 that start with it. For example, `ctl-x-map' is the keymap used for
943 characters following a `C-x'.
945 * `ctl-x-map' is the variable name for the map used for characters
948 * `help-map' is used for characters that follow `C-h'.
950 * `esc-map' is for characters that follow <ESC>. All Meta characters
951 are actually defined by this map.
953 * `ctl-x-4-map' is for characters that follow `C-x 4'.
955 * `mode-specific-map' is for characters that follow `C-c'.
957 The definition of a prefix key is the keymap to use for looking up
958 the following character. Sometimes the definition is actually a Lisp
959 symbol whose function definition is the following character keymap. The
960 effect is the same, but it provides a command name for the prefix key
961 that you can use as a description of what the prefix key is for. Thus
962 the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
963 definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
965 Prefix key definitions can appear in either the global map or a
966 local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
967 keys appear in the global map, so these prefix keys are always
968 available. Major modes can locally redefine a key as a prefix by
969 putting a prefix key definition for it in the local map.
971 A mode can also put a prefix definition of a global prefix character
972 such as `C-x' into its local map. This is how major modes override the
973 definitions of certain keys that start with `C-x'. This case is
974 special, because the local definition does not entirely replace the
975 global one. When both the global and local definitions of a key are
976 other keymaps, the next character is looked up in both keymaps, with
977 the local definition overriding the global one. The character after the
978 `C-x' is looked up in both the major mode's own keymap for redefined
979 `C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
980 `C-x' commands contains `nil', the definition from the global keymap
981 for `C-x' commands is used.
984 File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
986 Changing Key Bindings
987 ---------------------
989 You can redefine an Emacs key by changing its entry in a keymap.
990 You can change the global keymap, in which case the change is effective
991 in all major modes except those that have their own overriding local
992 definitions for the same key. Or you can change the current buffer's
993 local map, which affects all buffers using the same major mode.
997 * Interactive Rebinding:: Changing Key Bindings Interactively
998 * Programmatic Rebinding:: Changing Key Bindings Programmatically
999 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings
1002 File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
1004 Changing Key Bindings Interactively
1005 ...................................
1007 `M-x global-set-key <RET> KEY CMD <RET>'
1008 Defines KEY globally to run CMD.
1010 `M-x local-set-key <RET> KEYS CMD <RET>'
1011 Defines KEY locally (in the major mode now in effect) to run CMD.
1013 `M-x local-unset-key <RET> KEYS <RET>'
1014 Removes the local binding of KEY.
1016 CMD is a symbol naming an interactively-callable function.
1018 When called interactively, KEY is the next complete key sequence
1019 that you type. When called as a function, KEY is a string, a vector of
1020 events, or a vector of key-description lists as described in the
1021 `define-key' function description. The binding goes in the current
1022 buffer's local map, which is shared with other buffers in the same
1025 The following example:
1027 M-x global-set-key <RET> C-f next-line <RET>
1029 redefines `C-f' to move down a line. The fact that CMD is read second
1030 makes it serve as a kind of confirmation for KEY.
1032 These functions offer no way to specify a particular prefix keymap as
1033 the one to redefine in, but that is not necessary, as you can include
1034 prefixes in KEY. KEY is read by reading characters one by one until
1035 they amount to a complete key (that is, not a prefix key). Thus, if
1036 you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
1037 CMD. But if you type `C-x', another character is read; if that
1038 character is `4', another character is read, and so on. For example,
1040 M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
1042 redefines `C-x 4 $' to run the (fictitious) command
1043 `spell-other-window'.
1045 The most general way to modify a keymap is the function
1046 `define-key', used in Lisp code (such as your `.emacs' file).
1047 `define-key' takes three arguments: the keymap, the key to modify in
1048 it, and the new definition. *Note Init File::, for an example.
1049 `substitute-key-definition' is used similarly; it takes three
1050 arguments, an old definition, a new definition, and a keymap, and
1051 redefines in that keymap all keys that were previously defined with the
1052 old definition to have the new definition instead.
1055 File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
1057 Changing Key Bindings Programmatically
1058 ......................................
1060 You can use the functions `global-set-key' and `define-key' to
1061 rebind keys under program control.
1063 ``(global-set-key KEYS CMD)''
1064 Defines KEYS globally to run CMD.
1066 ``(define-key KEYMAP KEYS DEF)''
1067 Defines KEYS to run DEF in the keymap KEYMAP.
1069 KEYMAP is a keymap object.
1071 KEYS is the sequence of keystrokes to bind.
1073 DEF is anything that can be a key's definition:
1075 * `nil', meaning key is undefined in this keymap
1077 * A command, that is, a Lisp function suitable for interactive
1080 * A string or key sequence vector, which is treated as a keyboard
1083 * A keymap to define a prefix key
1085 * A symbol so that when the key is looked up, the symbol stands for
1086 its function definition, which should at that time be one of the
1087 above, or another symbol whose function definition is used, and so
1090 * A cons, `(string . defn)', meaning that DEFN is the definition
1091 (DEFN should be a valid definition in its own right)
1093 * A cons, `(keymap . char)', meaning use the definition of CHAR in
1096 For backward compatibility, XEmacs allows you to specify key
1097 sequences as strings. However, the preferred method is to use the
1098 representations of key sequences as vectors of keystrokes. *Note
1099 Keystrokes::, for more information about the rules for constructing key
1102 Emacs allows you to abbreviate representations for key sequences in
1103 most places where there is no ambiguity. Here are some rules for
1106 * The keysym by itself is equivalent to a list of just that keysym,
1107 i.e., `f1' is equivalent to `(f1)'.
1109 * A keystroke by itself is equivalent to a vector containing just
1110 that keystroke, i.e., `(control a)' is equivalent to `[(control
1113 * You can use ASCII codes for keysyms that have them. i.e., `65' is
1114 equivalent to `A'. (This is not so much an abbreviation as an
1115 alternate representation.)
1117 Here are some examples of programmatically binding keys:
1120 ;;; Bind `my-command' to <f1>
1121 (global-set-key 'f1 'my-command)
1123 ;;; Bind `my-command' to Shift-f1
1124 (global-set-key '(shift f1) 'my-command)
1126 ;;; Bind `my-command' to C-c Shift-f1
1127 (global-set-key '[(control c) (shift f1)] 'my-command)
1129 ;;; Bind `my-command' to the middle mouse button.
1130 (global-set-key 'button2 'my-command)
1132 ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
1133 ;;; in the keymap that is in force when you are running `dired'.
1134 (define-key dired-mode-map '(meta control button3) 'my-command)
1137 File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
1139 Using Strings for Changing Key Bindings
1140 .......................................
1142 For backward compatibility, you can still use strings to represent
1143 key sequences. Thus you can use commands like the following:
1145 ;;; Bind `end-of-line' to C-f
1146 (global-set-key "\C-f" 'end-of-line)
1148 Note, however, that in some cases you may be binding more than one
1149 key sequence by using a single command. This situation can arise
1150 because in ASCII, `C-i' and <TAB> have the same representation.
1151 Therefore, when Emacs sees:
1153 (global-set-key "\C-i" 'end-of-line)
1155 it is unclear whether the user intended to bind `C-i' or <TAB>. The
1156 solution XEmacs adopts is to bind both of these key sequences.
1158 After binding a command to two key sequences with a form like:
1160 (define-key global-map "\^X\^I" 'command-1)
1162 it is possible to redefine only one of those sequences like so:
1164 (define-key global-map [(control x) (control i)] 'command-2)
1165 (define-key global-map [(control x) tab] 'command-3)
1167 This applies only when running under a window system. If you are
1168 talking to Emacs through an ASCII-only channel, you do not get any of
1171 Here is a table of pairs of key sequences that behave in a similar
1180 control @ control space