1 This is Info file ../../info/xemacs.info, produced by Makeinfo version
2 1.68 from the input file xemacs.texi.
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: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
38 Here is an example of what a user option looks like in the
41 Kill Ring Max: [Hide] 30
42 [State]: this option is unchanged from its standard setting.
43 Maximum length of kill ring before oldest elements are thrown away.
45 The text following `[Hide]', `30' in this case, indicates the
46 current value of the option. If you see `[Show]' instead of `[Hide]',
47 it means that the value is hidden; the customization buffer initially
48 hides values that take up several lines. Invoke `[Show]' to show the
51 The line after the option name indicates the "customization state"
52 of the option: in the example above, it says you have not changed the
53 option yet. The word `[State]' at the beginning of this line is
54 active; you can get a menu of various operations by invoking it with
55 `Mouse-1' or <RET>. These operations are essential for customizing the
58 The line after the `[State]' line displays the beginning of the
59 option's documentation string. If there are more lines of
60 documentation, this line ends with `[More]'; invoke this to show the
61 full documentation string.
63 To enter a new value for `Kill Ring Max', move point to the value
64 and edit it textually. For example, you can type `M-d', then insert
67 When you begin to alter the text, you will see the `[State]' line
68 change to say that you have edited the value:
70 [State]: you have edited the value as text, but not set the option.
72 Editing the value does not actually set the option variable. To do
73 that, you must "set" the option. To do this, invoke the word `[State]'
74 and choose `Set for Current Session'.
76 The state of the option changes visibly when you set it:
78 [State]: you have set this option, but not saved it for future sessions.
80 You don't have to worry about specifying a value that is not valid;
81 setting the option checks for validity and will not really install an
84 While editing a value or field that is a file name, directory name,
85 command name, or anything else for which completion is defined, you can
86 type `M-<TAB>' (`widget-complete') to do completion.
88 Some options have a small fixed set of possible legitimate values.
89 These options don't let you edit the value textually. Instead, an
90 active field `[Value Menu]' appears before the value; invoke this field
91 to edit the value. For a boolean "on or off" value, the active field
92 says `[Toggle]', and it changes to the other value. `[Value Menu]' and
93 `[Toggle]' edit the buffer; the changes take effect when you use the
94 `Set for Current Session' operation.
96 Some options have values with complex structure. For example, the
97 value of `load-path' is a list of directories. Here is how it appears
98 in the customization buffer:
101 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
102 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
103 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
104 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
105 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
106 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
108 [State]: this item has been changed outside the customization buffer.
109 List of directories to search for files to load....
111 Each directory in the list appears on a separate line, and each line has
112 several editable or active fields.
114 You can edit any of the directory names. To delete a directory from
115 the list, invoke `[DEL]' on that line. To insert a new directory in
116 the list, invoke `[INS]' at the point where you want to insert it.
118 You can also invoke `[Current dir?]' to switch between including a
119 specific named directory in the path, and including `nil' in the path.
120 (`nil' in a search path means "try the current directory.")
122 Two special commands, <TAB> and `S-<TAB>', are useful for moving
123 through the customization buffer. <TAB> (`widget-forward') moves
124 forward to the next active or editable field; `S-<TAB>'
125 (`widget-backward') moves backward to the previous active or editable
128 Typing <RET> on an editable field also moves forward, just like
129 <TAB>. The reason for this is that people have a tendency to type
130 <RET> when they are finished editing a field. If you have occasion to
131 insert a newline in an editable field, use `C-o' or `C-q C-j',
133 Setting the option changes its value in the current Emacs session;
134 "saving" the value changes it for future sessions as well. This works
135 by writing code into your `~/.emacs' file so as to set the option
136 variable again each time you start Emacs. To save the option, invoke
137 `[State]' and select the `Save for Future Sessions' operation.
139 You can also restore the option to its standard value by invoking
140 `[State]' and selecting the `Reset' operation. There are actually
141 three reset operations:
144 If you have made some modifications and not yet set the option,
145 this restores the text in the customization buffer to match the
149 This restores the value of the option to the last saved value, and
150 updates the text accordingly.
152 `Reset to Standard Settings'
153 This sets the option to its standard value, and updates the text
154 accordingly. This also eliminates any saved value for the option,
155 so that you will get the standard value in future Emacs sessions.
157 The state of a group indicates whether anything in that group has
158 been edited, set or saved. You can select `Set for Current Session',
159 `Save for Future Sessions' and the various kinds of `Reset' operation
160 for the group; these operations on the group apply to all options in
161 the group and its subgroups.
163 Near the top of the customization buffer there are two lines
164 containing several active fields:
166 [Set] [Save] [Reset] [Done]
168 Invoking `[Done]' buries this customization buffer. Each of the other
169 fields performs an operation--set, save or reset--on each of the items
170 in the buffer that could meaningfully be set, saved or reset.
173 File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
178 In addition to user options, some customization groups also include
179 faces. When you show the contents of a group, both the user options and
180 the faces in the group appear in the customization buffer. Here is an
181 example of how a face looks:
183 Custom Changed Face: (sample)
184 [State]: this face is unchanged from its standard setting.
185 Face used when the customize item has been changed.
186 Parent groups: [Custom Magic Faces]
187 Attributes: [ ] Bold: [Toggle] off (nil)
188 [ ] Italic: [Toggle] off (nil)
189 [ ] Underline: [Toggle] off (nil)
190 [ ] Foreground: white (sample)
191 [ ] Background: blue (sample)
192 [ ] Inverse: [Toggle] off (nil)
198 Each face attribute has its own line. The `[X]' field before the
199 attribute name indicates whether the attribute is "enabled"; `X' means
200 that it is. You can enable or disable the attribute by invoking that
201 field. When the attribute is enabled, you can change the attribute
202 value in the usual ways.
204 Setting, saving and resetting a face work like the same operations
205 for options (*note Changing an Option::.).
207 A face can specify different appearances for different types of
208 display. For example, a face can make text red on a color display, but
209 use a bold font on a monochrome display. To specify multiple
210 appearances for a face, select `Show Display Types' in the menu you get
211 from invoking `[State]'.
214 File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
216 Customizing Specific Items
217 ..........................
219 Instead of finding the options you want to change by moving down
220 through the structure of groups, you can specify the particular option,
221 face or group that you want to customize.
223 `M-x customize-option <RET> OPTION <RET>'
224 Set up a customization buffer with just one option, OPTION.
226 `M-x customize-face <RET> FACE <RET>'
227 Set up a customization buffer with just one face, FACE.
229 `M-x customize-group <RET> GROUP <RET>'
230 Set up a customization buffer with just one group, GROUP.
232 `M-x customize-apropos <RET> REGEXP <RET>'
233 Set up a customization buffer with all the options, faces and
234 groups that match REGEXP.
236 `M-x customize-saved'
237 Set up a customization buffer containing all options and faces
238 that you have saved with customization buffers.
240 `M-x customize-customized'
241 Set up a customization buffer containing all options and faces
242 that you have customized but not saved.
244 If you want to alter a particular user option variable with the
245 customization buffer, and you know its name, you can use the command
246 `M-x customize-option' and specify the option name. This sets up the
247 customization buffer with just one option--the one that you asked for.
248 Editing, setting and saving the value work as described above, but only
249 for the specified option.
251 Likewise, you can modify a specific face, chosen by name, using `M-x
254 You can also set up the customization buffer with a specific group,
255 using `M-x customize-group'. The immediate contents of the chosen
256 group, including option variables, faces, and other groups, all appear
257 as well. However, these subgroups' own contents start out hidden. You
258 can show their contents in the usual way, by invoking `[Show]'.
260 To control more precisely what to customize, you can use `M-x
261 customize-apropos'. You specify a regular expression as argument; then
262 all options, faces and groups whose names match this regular expression
263 are set up in the customization buffer. If you specify an empty regular
264 expression, this includes *all* groups, options and faces in the
265 customization buffer (but that takes a long time).
267 If you change option values and then decide the change was a mistake,
268 you can use two special commands to revisit your previous changes. Use
269 `customize-saved' to look at the options and faces that you have saved.
270 Use `M-x customize-customized' to look at the options and faces that
271 you have set but not saved.
274 File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
276 Editing Variable Values
277 -----------------------
280 Display a buffer listing names, values, and documentation of all
284 Change option values by editing a list of options.
286 `M-x list-options' displays a list of all Emacs option variables in
287 an Emacs buffer named `*List Options*'. Each option is shown with its
288 documentation and its current value. Here is what a portion of it might
292 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
293 *List of directories to search programs to run in subprocesses.
294 Each element is a string (directory name)
295 or nil (try the default directory).
299 *Column beyond which automatic line-wrapping should happen.
300 Automatically becomes local when set in any fashion.
303 `M-x edit-options' goes one step further and immediately selects the
304 `*List Options*' buffer; this buffer uses the major mode Options mode,
305 which provides commands that allow you to point at an option and change
309 Set the variable point is in or near to a new value read using the
313 Toggle the variable point is in or near: if the value was `nil',
314 it becomes `t'; otherwise it becomes `nil'.
317 Set the variable point is in or near to `t'.
320 Set the variable point is in or near to `nil'.
324 Move to the next or previous variable.
327 File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
332 `M-x make-local-variable'
333 Make a variable have a local value in the current buffer.
335 `M-x kill-local-variable'
336 Make a variable use its global value in the current buffer.
338 `M-x make-variable-buffer-local'
339 Mark a variable so that setting it will make it local to the
340 buffer that is current at that time.
342 You can make any variable "local" to a specific Emacs buffer. This
343 means that the variable's value in that buffer is independent of its
344 value in other buffers. A few variables are always local in every
345 buffer. All other Emacs variables have a "global" value which is in
346 effect in all buffers that have not made the variable local.
348 Major modes always make the variables they set local to the buffer.
349 This is why changing major modes in one buffer has no effect on other
352 `M-x make-local-variable' reads the name of a variable and makes it
353 local to the current buffer. Further changes in this buffer will not
354 affect others, and changes in the global value will not affect this
357 `M-x make-variable-buffer-local' reads the name of a variable and
358 changes the future behavior of the variable so that it automatically
359 becomes local when it is set. More precisely, once you have marked a
360 variable in this way, the usual ways of setting the variable will
361 automatically invoke `make-local-variable' first. We call such
362 variables "per-buffer" variables.
364 Some important variables have been marked per-buffer already. They
365 include `abbrev-mode', `auto-fill-function', `case-fold-search',
366 `comment-column', `ctl-arrow', `fill-column', `fill-prefix',
367 `indent-tabs-mode', `left-margin',
368 `mode-line-format', `overwrite-mode', `selective-display-ellipses',
369 `selective-display', `tab-width', and `truncate-lines'. Some other
370 variables are always local in every buffer, but they are used for
373 Note: the variable `auto-fill-function' was formerly named
376 If you want a variable to cease to be local to the current buffer,
377 call `M-x kill-local-variable' and provide the name of a variable to
378 the prompt. The global value of the variable is again in effect in
379 this buffer. Setting the major mode kills all the local variables of
382 To set the global value of a variable, regardless of whether the
383 variable has a local value in the current buffer, you can use the Lisp
384 function `setq-default'. It works like `setq'. If there is a local
385 value in the current buffer, the local value is not affected by
386 `setq-default'; thus, the new global value may not be visible until you
387 switch to another buffer, as in the case of:
389 (setq-default fill-column 75)
391 `setq-default' is the only way to set the global value of a variable
392 that has been marked with `make-variable-buffer-local'.
394 Programs can look at a variable's default value with `default-value'.
395 This function takes a symbol as an argument and returns its default
396 value. The argument is evaluated; usually you must quote it
397 explicitly, as in the case of:
399 (default-value 'fill-column)
402 File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables
404 Local Variables in Files
405 ------------------------
407 A file can contain a "local variables list", which specifies the
408 values to use for certain Emacs variables when that file is edited.
409 Visiting the file checks for a local variables list and makes each
410 variable in the list local to the buffer in which the file is visited,
411 with the value specified in the file.
413 A local variables list goes near the end of the file, in the last
414 page. (It is often best to put it on a page by itself.) The local
415 variables list starts with a line containing the string `Local
416 Variables:', and ends with a line containing the string `End:'. In
417 between come the variable names and values, one set per line, as
418 `VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
421 The line which starts the local variables list does not have to say
422 just `Local Variables:'. If there is other text before `Local
423 Variables:', that text is called the "prefix", and if there is other
424 text after, that is called the "suffix". If a prefix or suffix are
425 present, each entry in the local variables list should have the prefix
426 before it and the suffix after it. This includes the `End:' line. The
427 prefix and suffix are included to disguise the local variables list as
428 a comment so the compiler or text formatter will ignore it. If you do
429 not need to disguise the local variables list as a comment in this way,
430 there is no need to include a prefix or a suffix.
432 Two "variable" names are special in a local variables list: a value
433 for the variable `mode' sets the major mode, and a value for the
434 variable `eval' is simply evaluated as an expression and the value is
435 ignored. These are not real variables; setting them in any other
436 context does not have the same effect. If `mode' is used in a local
437 variables list, it should be the first entry in the list.
439 Here is an example of a local variables list:
440 ;;; Local Variables: ***
442 ;;; comment-column:0 ***
443 ;;; comment-start: ";;; " ***
444 ;;; comment-end:"***" ***
447 Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
448 that comments in the file begin with and end with the same strings.
449 Presumably the file contains code in a language which is enough like
450 Lisp for Lisp mode to be useful but in which comments start and end
451 differently. The prefix and suffix are used in the local variables
452 list to make the list look like several lines of comments when the
453 compiler or interpreter for that language reads the file.
455 The start of the local variables list must be no more than 3000
456 characters from the end of the file, and must be in the last page if the
457 file is divided into pages. Otherwise, Emacs will not notice it is
458 there. The purpose is twofold: a stray `Local Variables:' not in the
459 last page does not confuse Emacs, and Emacs never needs to search a
460 long file that contains no page markers and has no local variables list.
462 You may be tempted to turn on Auto Fill mode with a local variable
463 list. That is inappropriate. Whether you use Auto Fill mode or not is
464 a matter of personal taste, not a matter of the contents of particular
465 files. If you want to use Auto Fill, set up major mode hooks with your
466 `.emacs' file to turn it on (when appropriate) for you alone (*note
467 Init File::.). Don't try to use a local variable list that would
468 impose your taste on everyone working with the file.
470 XEmacs allows you to specify local variables in the first line of a
471 file, in addition to specifying them in the `Local Variables' section
472 at the end of a file.
474 If the first line of a file contains two occurrences of ``-*-'',
475 XEmacs uses the information between them to determine what the major
476 mode and variable settings should be. For example, these are all legal:
478 ;;; -*- mode: emacs-lisp -*-
479 ;;; -*- mode: postscript; version-control: never -*-
480 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
482 For historical reasons, the syntax ``-*- modename -*-'' is allowed
483 as well; for example, you can use:
485 ;;; -*- emacs-lisp -*-
487 The variable `enable-local-variables' controls the use of local
488 variables lists in files you visit. The value can be `t', `nil', or
489 something else. A value of `t' means local variables lists are obeyed;
490 `nil' means they are ignored; anything else means query.
492 The command `M-x normal-mode' always obeys local variables lists and
493 ignores this variable.
496 File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization
501 A "keyboard macro" is a command defined by the user to abbreviate a
502 sequence of keys. For example, if you discover that you are about to
503 type `C-n C-d' forty times, you can speed your work by defining a
504 keyboard macro to invoke `C-n C-d' and calling it with a repeat count
508 Start defining a keyboard macro (`start-kbd-macro').
511 End the definition of a keyboard macro (`end-kbd-macro').
514 Execute the most recent keyboard macro (`call-last-kbd-macro').
517 Re-execute last keyboard macro, then add more keys to its
521 When this point is reached during macro execution, ask for
522 confirmation (`kbd-macro-query').
524 `M-x name-last-kbd-macro'
525 Give a command name (for the duration of the session) to the most
526 recently defined keyboard macro.
528 `M-x insert-kbd-macro'
529 Insert in the buffer a keyboard macro's definition, as Lisp code.
531 Keyboard macros differ from other Emacs commands in that they are
532 written in the Emacs command language rather than in Lisp. This makes
533 it easier for the novice to write them and makes them more convenient as
534 temporary hacks. However, the Emacs command language is not powerful
535 enough as a programming language to be useful for writing anything
536 general or complex. For such things, Lisp must be used.
538 You define a keyboard macro by executing the commands which are its
539 definition. Put differently, as you are defining a keyboard macro, the
540 definition is being executed for the first time. This way, you see
541 what the effects of your commands are, and don't have to figure them
542 out in your head. When you are finished, the keyboard macro is defined
543 and also has been executed once. You can then execute the same set of
544 commands again by invoking the macro.
548 * Basic Kbd Macro:: Defining and running keyboard macros.
549 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
550 * Kbd Macro Query:: Keyboard macros that do different things each use.
553 File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
558 To start defining a keyboard macro, type `C-x ('
559 (`start-kbd-macro'). From then on, anything you type continues to be
560 executed, but also becomes part of the definition of the macro. `Def'
561 appears in the mode line to remind you of what is going on. When you
562 are finished, the `C-x )' command (`end-kbd-macro') terminates the
563 definition, without becoming part of it.
569 defines a macro to move forward a word and then insert `foo'.
571 You can give `C-x )' a repeat count as an argument, in which case it
572 repeats the macro that many times right after defining it, but defining
573 the macro counts as the first repetition (since it is executed as you
574 define it). If you give `C-x )' an argument of 4, it executes the
575 macro immediately 3 additional times. An argument of zero to `C-x e'
576 or `C-x )' means repeat the macro indefinitely (until it gets an error
579 Once you have defined a macro, you can invoke it again with the `C-x
580 e' command (`call-last-kbd-macro'). You can give the command a repeat
581 count numeric argument to execute the macro many times.
583 To repeat an operation at regularly spaced places in the text,
584 define a macro and include as part of the macro the commands to move to
585 the next place you want to use it. For example, if you want to change
586 each line, you should position point at the start of a line, and define
587 a macro to change that line and leave point at the start of the next
588 line. Repeating the macro will then operate on successive lines.
590 After you have terminated the definition of a keyboard macro, you
591 can add to the end of its definition by typing `C-u C-x ('. This is
592 equivalent to plain `C-x (' followed by retyping the whole definition
593 so far. As a consequence it re-executes the macro as previously
597 File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
599 Naming and Saving Keyboard Macros
600 ---------------------------------
602 To save a keyboard macro for longer than until you define the next
603 one, you must give it a name using `M-x name-last-kbd-macro'. This
604 reads a name as an argument using the minibuffer and defines that name
605 to execute the macro. The macro name is a Lisp symbol, and defining it
606 in this way makes it a valid command name for calling with `M-x' or for
607 binding a key to with `global-set-key' (*note Keymaps::.). If you
608 specify a name that has a prior definition other than another keyboard
609 macro, Emacs prints an error message and nothing is changed.
611 Once a macro has a command name, you can save its definition in a
612 file. You can then use it in another editing session. First visit the
613 file you want to save the definition in. Then use the command:
615 M-x insert-kbd-macro <RET> MACRONAME <RET>
617 This inserts some Lisp code that, when executed later, will define the
618 same macro with the same definition it has now. You need not
619 understand Lisp code to do this, because `insert-kbd-macro' writes the
620 Lisp code for you. Then save the file. You can load the file with
621 `load-file' (*note Lisp Libraries::.). If the file you save in is your
622 initialization file `~/.emacs' (*note Init File::.), then the macro
623 will be defined each time you run Emacs.
625 If you give `insert-kbd-macro' a prefix argument, it creates
626 additional Lisp code to record the keys (if any) that you have bound to
627 the keyboard macro, so that the macro is reassigned the same keys when
631 File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
633 Executing Macros With Variations
634 --------------------------------
636 You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
637 that of `query-replace'. The macro asks you each time whether to make
638 a change. When you are defining the macro, type `C-x q' at the point
639 where you want the query to occur. During macro definition, the `C-x
640 q' does nothing, but when you invoke the macro, `C-x q' reads a
641 character from the terminal to decide whether to continue.
643 The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
644 `C-l', and `C-r'. Any other character terminates execution of the
645 keyboard macro and is then read as a command. <SPC> means to continue.
646 <DEL> means to skip the remainder of this repetition of the macro,
647 starting again from the beginning in the next repetition. `C-d' means
648 to skip the remainder of this repetition and cancel further repetition.
649 `C-l' redraws the frame and asks you again for a character to specify
650 what to do. `C-r' enters a recursive editing level, in which you can
651 perform editing that is not part of the macro. When you exit the
652 recursive edit using `C-M-c', you are asked again how to continue with
653 the keyboard macro. If you type a <SPC> at this time, the rest of the
654 macro definition is executed. It is up to you to leave point and the
655 text in a state such that the rest of the macro will do what you want.
657 `C-u C-x q', which is `C-x q' with a numeric argument, performs a
658 different function. It enters a recursive edit reading input from the
659 keyboard, both when you type it during the definition of the macro and
660 when it is executed from the macro. During definition, the editing you
661 do inside the recursive edit does not become part of the macro. During
662 macro execution, the recursive edit gives you a chance to do some
663 particularized editing. *Note Recursive Edit::.
666 File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
668 Customizing Key Bindings
669 ========================
671 This section deals with the "keymaps" that define the bindings
672 between keys and functions, and shows how you can customize these
675 A command is a Lisp function whose definition provides for
676 interactive use. Like every Lisp function, a command has a function
677 name, which is a Lisp symbol whose name usually consists of lower case
682 * Keymaps:: Definition of the keymap data structure.
683 Names of Emacs's standard keymaps.
684 * Rebinding:: How to redefine one key's meaning conveniently.
685 * Disabling:: Disabling a command means confirmation is required
686 before it can be executed. This is done to protect
687 beginners from surprises.
690 File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
695 The bindings between characters and command functions are recorded in
696 data structures called "keymaps". Emacs has many of these. One, the
697 "global" keymap, defines the meanings of the single-character keys that
698 are defined regardless of major mode. It is the value of the variable
701 Each major mode has another keymap, its "local keymap", which
702 contains overriding definitions for the single-character keys that are
703 redefined in that mode. Each buffer records which local keymap is
704 installed for it at any time, and the current buffer's local keymap is
705 the only one that directly affects command execution. The local keymaps
706 for Lisp mode, C mode, and many other major modes always exist even when
707 not in use. They are the values of the variables `lisp-mode-map',
708 `c-mode-map', and so on. For less frequently used major modes, the
709 local keymap is sometimes constructed only when the mode is used for the
710 first time in a session, to save space.
712 There are local keymaps for the minibuffer, too; they contain various
713 completion and exit commands.
715 * `minibuffer-local-map' is used for ordinary input (no completion).
717 * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
718 like <RET>. This is used mainly for Mocklisp compatibility.
720 * `minibuffer-local-completion-map' is for permissive completion.
722 * `minibuffer-local-must-match-map' is for strict completion and for
725 * `repeat-complex-command-map' is for use in `C-x <ESC>'.
727 * `isearch-mode-map' contains the bindings of the special keys which
728 are bound in the pseudo-mode entered with `C-s' and `C-r'.
730 Finally, each prefix key has a keymap which defines the key sequences
731 that start with it. For example, `ctl-x-map' is the keymap used for
732 characters following a `C-x'.
734 * `ctl-x-map' is the variable name for the map used for characters
737 * `help-map' is used for characters that follow `C-h'.
739 * `esc-map' is for characters that follow <ESC>. All Meta characters
740 are actually defined by this map.
742 * `ctl-x-4-map' is for characters that follow `C-x 4'.
744 * `mode-specific-map' is for characters that follow `C-c'.
746 The definition of a prefix key is the keymap to use for looking up
747 the following character. Sometimes the definition is actually a Lisp
748 symbol whose function definition is the following character keymap. The
749 effect is the same, but it provides a command name for the prefix key
750 that you can use as a description of what the prefix key is for. Thus
751 the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
752 definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
754 Prefix key definitions can appear in either the global map or a
755 local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
756 keys appear in the global map, so these prefix keys are always
757 available. Major modes can locally redefine a key as a prefix by
758 putting a prefix key definition for it in the local map.
760 A mode can also put a prefix definition of a global prefix character
761 such as `C-x' into its local map. This is how major modes override the
762 definitions of certain keys that start with `C-x'. This case is
763 special, because the local definition does not entirely replace the
764 global one. When both the global and local definitions of a key are
765 other keymaps, the next character is looked up in both keymaps, with
766 the local definition overriding the global one. The character after the
767 `C-x' is looked up in both the major mode's own keymap for redefined
768 `C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
769 `C-x' commands contains `nil', the definition from the global keymap
770 for `C-x' commands is used.
773 File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
775 Changing Key Bindings
776 ---------------------
778 You can redefine an Emacs key by changing its entry in a keymap.
779 You can change the global keymap, in which case the change is effective
780 in all major modes except those that have their own overriding local
781 definitions for the same key. Or you can change the current buffer's
782 local map, which affects all buffers using the same major mode.
786 * Interactive Rebinding:: Changing Key Bindings Interactively
787 * Programmatic Rebinding:: Changing Key Bindings Programmatically
788 * Key Bindings Using Strings::Using Strings for Changing Key Bindings
791 File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
793 Changing Key Bindings Interactively
794 ...................................
796 `M-x global-set-key <RET> KEY CMD <RET>'
797 Defines KEY globally to run CMD.
799 `M-x local-set-key <RET> KEYS CMD <RET>'
800 Defines KEY locally (in the major mode now in effect) to run CMD.
802 `M-x local-unset-key <RET> KEYS <RET>'
803 Removes the local binding of KEY.
805 CMD is a symbol naming an interactively-callable function.
807 When called interactively, KEY is the next complete key sequence
808 that you type. When called as a function, KEY is a string, a vector of
809 events, or a vector of key-description lists as described in the
810 `define-key' function description. The binding goes in the current
811 buffer's local map, which is shared with other buffers in the same
814 The following example:
816 M-x global-set-key <RET> C-f next-line <RET>
818 redefines `C-f' to move down a line. The fact that CMD is read second
819 makes it serve as a kind of confirmation for KEY.
821 These functions offer no way to specify a particular prefix keymap as
822 the one to redefine in, but that is not necessary, as you can include
823 prefixes in KEY. KEY is read by reading characters one by one until
824 they amount to a complete key (that is, not a prefix key). Thus, if
825 you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
826 CMD. But if you type `C-x', another character is read; if that
827 character is `4', another character is read, and so on. For example,
829 M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
831 redefines `C-x 4 $' to run the (fictitious) command
832 `spell-other-window'.
834 The most general way to modify a keymap is the function
835 `define-key', used in Lisp code (such as your `.emacs' file).
836 `define-key' takes three arguments: the keymap, the key to modify in
837 it, and the new definition. *Note Init File::, for an example.
838 `substitute-key-definition' is used similarly; it takes three
839 arguments, an old definition, a new definition, and a keymap, and
840 redefines in that keymap all keys that were previously defined with the
841 old definition to have the new definition instead.
844 File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
846 Changing Key Bindings Programmatically
847 ......................................
849 You can use the functions `global-set-key' and `define-key' to
850 rebind keys under program control.
852 ``(global-set-key KEYS CMD)''
853 Defines KEYS globally to run CMD.
855 ``(define-key KEYMAP KEYS DEF)''
856 Defines KEYS to run DEF in the keymap KEYMAP.
858 KEYMAP is a keymap object.
860 KEYS is the sequence of keystrokes to bind.
862 DEF is anything that can be a key's definition:
864 * `nil', meaning key is undefined in this keymap
866 * A command, that is, a Lisp function suitable for interactive
869 * A string or key sequence vector, which is treated as a keyboard
872 * A keymap to define a prefix key
874 * A symbol so that when the key is looked up, the symbol stands for
875 its function definition, which should at that time be one of the
876 above, or another symbol whose function definition is used, and so
879 * A cons, `(string . defn)', meaning that DEFN is the definition
880 (DEFN should be a valid definition in its own right)
882 * A cons, `(keymap . char)', meaning use the definition of CHAR in
885 For backward compatibility, XEmacs allows you to specify key
886 sequences as strings. However, the preferred method is to use the
887 representations of key sequences as vectors of keystrokes. *Note
888 Keystrokes::, for more information about the rules for constructing key
891 Emacs allows you to abbreviate representations for key sequences in
892 most places where there is no ambiguity. Here are some rules for
895 * The keysym by itself is equivalent to a list of just that keysym,
896 i.e., `f1' is equivalent to `(f1)'.
898 * A keystroke by itself is equivalent to a vector containing just
899 that keystroke, i.e., `(control a)' is equivalent to `[(control
902 * You can use ASCII codes for keysyms that have them. i.e., `65' is
903 equivalent to `A'. (This is not so much an abbreviation as an
904 alternate representation.)
906 Here are some examples of programmatically binding keys:
909 ;;; Bind `my-command' to <f1>
910 (global-set-key 'f1 'my-command)
912 ;;; Bind `my-command' to Shift-f1
913 (global-set-key '(shift f1) 'my-command)
915 ;;; Bind `my-command' to C-c Shift-f1
916 (global-set-key '[(control c) (shift f1)] 'my-command)
918 ;;; Bind `my-command' to the middle mouse button.
919 (global-set-key 'button2 'my-command)
921 ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
922 ;;; in the keymap that is in force when you are running `dired'.
923 (define-key dired-mode-map '(meta control button3) 'my-command)
926 File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
928 Using Strings for Changing Key Bindings
929 .......................................
931 For backward compatibility, you can still use strings to represent
932 key sequences. Thus you can use commands like the following:
934 ;;; Bind `end-of-line' to C-f
935 (global-set-key "\C-f" 'end-of-line)
937 Note, however, that in some cases you may be binding more than one
938 key sequence by using a single command. This situation can arise
939 because in ASCII, `C-i' and <TAB> have the same representation.
940 Therefore, when Emacs sees:
942 (global-set-key "\C-i" 'end-of-line)
944 it is unclear whether the user intended to bind `C-i' or <TAB>. The
945 solution XEmacs adopts is to bind both of these key sequences.
947 After binding a command to two key sequences with a form like:
949 (define-key global-map "\^X\^I" 'command-1)
951 it is possible to redefine only one of those sequences like so:
953 (define-key global-map [(control x) (control i)] 'command-2)
954 (define-key global-map [(control x) tab] 'command-3)
956 This applies only when running under a window system. If you are
957 talking to Emacs through an ASCII-only channel, you do not get any of
960 Here is a table of pairs of key sequences that behave in a similar
969 control @ control space
972 File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
977 Disabling a command marks it as requiring confirmation before it can
978 be executed. The purpose of disabling a command is to prevent
979 beginning users from executing it by accident and being confused.
981 The direct mechanism for disabling a command is to have a non-`nil'
982 `disabled' property on the Lisp symbol for the command. These
983 properties are normally set by the user's `.emacs' file with Lisp
986 (put 'delete-region 'disabled t)
988 If the value of the `disabled' property is a string, that string is
989 included in the message printed when the command is used:
991 (put 'delete-region 'disabled
992 "Text deleted this way cannot be yanked back!\n")
994 You can disable a command either by editing the `.emacs' file
995 directly or with the command `M-x disable-command', which edits the
996 `.emacs' file for you. *Note Init File::.
998 When you attempt to invoke a disabled command interactively in Emacs,
999 a window is displayed containing the command's name, its documentation,
1000 and some instructions on what to do next; then Emacs asks for input
1001 saying whether to execute the command as requested, enable it and
1002 execute, or cancel it. If you decide to enable the command, you are
1003 asked whether to do this permanently or just for the current session.
1004 Enabling permanently works by automatically editing your `.emacs' file.
1005 You can use `M-x enable-command' at any time to enable any command
1008 Whether a command is disabled is independent of what key is used to
1009 invoke it; it also applies if the command is invoked using `M-x'.
1010 Disabling a command has no effect on calling it as a function from Lisp
1014 File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization
1019 All the Emacs commands which parse words or balance parentheses are
1020 controlled by the "syntax table". The syntax table specifies which
1021 characters are opening delimiters, which are parts of words, which are
1022 string quotes, and so on. Actually, each major mode has its own syntax
1023 table (though sometimes related major modes use the same one) which it
1024 installs in each buffer that uses that major mode. The syntax table
1025 installed in the current buffer is the one that all commands use, so we
1026 call it "the" syntax table. A syntax table is a Lisp object, a vector
1027 of length 256 whose elements are numbers.
1031 * Entry: Syntax Entry. What the syntax table records for each character.
1032 * Change: Syntax Change. How to change the information.
1035 File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax
1037 Information About Each Character
1038 --------------------------------
1040 The syntax table entry for a character is a number that encodes six
1041 pieces of information:
1043 * The syntactic class of the character, represented as a small
1046 * The matching delimiter, for delimiter characters only (the
1047 matching delimiter of `(' is `)', and vice versa)
1049 * A flag saying whether the character is the first character of a
1050 two-character comment starting sequence
1052 * A flag saying whether the character is the second character of a
1053 two-character comment starting sequence
1055 * A flag saying whether the character is the first character of a
1056 two-character comment ending sequence
1058 * A flag saying whether the character is the second character of a
1059 two-character comment ending sequence
1061 The syntactic classes are stored internally as small integers, but
1062 are usually described to or by the user with characters. For example,
1063 `(' is used to specify the syntactic class of opening delimiters. Here
1064 is a table of syntactic classes, with the characters that specify them.
1067 The class of whitespace characters.
1070 The class of word-constituent characters.
1073 The class of characters that are part of symbol names but not
1074 words. This class is represented by `_' because the character `_'
1075 has this class in both C and Lisp.
1078 The class of punctuation characters that do not fit into any other
1082 The class of opening delimiters.
1085 The class of closing delimiters.
1088 The class of expression-adhering characters. These characters are
1089 part of a symbol if found within or adjacent to one, and are part
1090 of a following expression if immediately preceding one, but are
1091 like whitespace if surrounded by whitespace.
1094 The class of string-quote characters. They match each other in
1095 pairs, and the characters within the pair all lose their syntactic
1096 significance except for the `\' and `/' classes of escape
1097 characters, which can be used to include a string-quote inside the
1101 The class of self-matching delimiters. This is intended for TeX's
1102 `$', which is used both to enter and leave math mode. Thus, a
1103 pair of matching `$' characters surround each piece of math mode
1104 TeX input. A pair of adjacent `$' characters act like a single
1105 one for purposes of matching.
1108 The class of escape characters that always just deny the following
1109 character its special syntactic significance. The character after
1110 one of these escapes is always treated as alphabetic.
1113 The class of C-style escape characters. In practice, these are
1114 treated just like `/'-class characters, because the extra
1115 possibilities for C escapes (such as being followed by digits)
1116 have no effect on where the containing expression ends.
1119 The class of comment-starting characters. Only single-character
1120 comment starters (such as `;' in Lisp mode) are represented this
1124 The class of comment-ending characters. Newline has this syntax in
1127 The characters flagged as part of two-character comment delimiters
1128 can have other syntactic functions most of the time. For example, `/'
1129 and `*' in C code, when found separately, have nothing to do with
1130 comments. The comment-delimiter significance overrides when the pair of
1131 characters occur together in the proper order. Only the list and sexp
1132 commands use the syntax table to find comments; the commands
1133 specifically for comments have other variables that tell them where to
1134 find comments. Moreover, the list and sexp commands notice comments
1135 only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set
1136 to `nil' in modes where comment-terminator sequences are liable to
1137 appear where there is no comment, for example, in Lisp mode where the
1138 comment terminator is a newline but not every newline ends a comment.
1141 File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax
1143 Altering Syntax Information
1144 ---------------------------
1146 It is possible to alter a character's syntax table entry by storing
1147 a new number in the appropriate element of the syntax table, but it
1148 would be hard to determine what number to use. Emacs therefore
1149 provides a command that allows you to specify the syntactic properties
1150 of a character in a convenient way.
1152 `M-x modify-syntax-entry' is the command to change a character's
1153 syntax. It can be used interactively and is also used by major modes
1154 to initialize their own syntax tables. Its first argument is the
1155 character to change. The second argument is a string that specifies the
1156 new syntax. When called from Lisp code, there is a third, optional
1157 argument, which specifies the syntax table in which to make the change.
1158 If not supplied, or if this command is called interactively, the third
1159 argument defaults to the current buffer's syntax table.
1161 1. The first character in the string specifies the syntactic class.
1162 It is one of the characters in the previous table (*note Syntax
1165 2. The second character is the matching delimiter. For a character
1166 that is not an opening or closing delimiter, this should be a
1167 space, and may be omitted if no following characters are needed.
1169 3. The remaining characters are flags. The flag characters allowed
1173 Flag this character as the first of a two-character comment
1177 Flag this character as the second of a two-character comment
1181 Flag this character as the first of a two-character comment
1185 Flag this character as the second of a two-character comment
1188 Use `C-h s' (`describe-syntax') to display a description of the
1189 contents of the current syntax table. The description of each
1190 character includes both the string you have to pass to
1191 `modify-syntax-entry' to set up that character's current syntax, and
1192 some English to explain that string if necessary.