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: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
35 Recursive Editing Levels
36 ========================
38 A "recursive edit" is a situation in which you are using XEmacs
39 commands to perform arbitrary editing while in the middle of another
40 XEmacs command. For example, when you type `C-r' inside a
41 `query-replace', you enter a recursive edit in which you can change the
42 current buffer. When you exit from the recursive edit, you go back to
45 "Exiting" a recursive edit means returning to the unfinished
46 command, which continues execution. For example, exiting the recursive
47 edit requested by `C-r' in `query-replace' causes query replacing to
48 resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
50 You can also "abort" a recursive edit. This is like exiting, but
51 also quits the unfinished command immediately. Use the command `C-]'
52 (`abort-recursive-edit') for this. *Note Quitting::.
54 The mode line shows you when you are in a recursive edit by
55 displaying square brackets around the parentheses that always surround
56 the major and minor mode names. Every window's mode line shows the
57 square brackets, since XEmacs as a whole, rather than any particular
58 buffer, is in a recursive edit.
60 It is possible to be in recursive edits within recursive edits. For
61 example, after typing `C-r' in a `query-replace', you might type a
62 command that entered the debugger. In such a case, two or more sets of
63 square brackets appear in the mode line(s). Exiting the inner
64 recursive edit (here with the debugger `c' command) resumes the
65 query-replace command where it called the debugger. After the end of
66 the query-replace command, you would be able to exit the first
67 recursive edit. Aborting exits only one level of recursive edit; it
68 returns to the command level of the previous recursive edit. You can
69 then abort that one as well.
71 The command `M-x top-level' aborts all levels of recursive edits,
72 returning immediately to the top level command reader.
74 The text you edit inside the recursive edit need not be the same text
75 that you were editing at top level. If the command that invokes the
76 recursive edit selects a different buffer first, that is the buffer you
77 will edit recursively. You can switch buffers within the recursive edit
78 in the normal manner (as long as the buffer-switching keys have not been
79 rebound). While you could theoretically do the rest of your editing
80 inside the recursive edit, including visiting files, this could have
81 surprising effects (such as stack overflow) from time to time. It is
82 best if you always exit or abort a recursive edit when you no longer
85 In general, XEmacs tries to avoid using recursive edits. It is
86 usually preferable to allow users to switch among the possible editing
87 modes in any order they like. With recursive edits, the only way to get
88 to another state is to go "back" to the state that the recursive edit
92 File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
97 `M-x dissociated-press' is a command for scrambling a file of text
98 either word by word or character by character. Starting from a buffer
99 of straight English, it produces extremely amusing output. The input
100 comes from the current XEmacs buffer. Dissociated Press writes its
101 output in a buffer named `*Dissociation*', and redisplays that buffer
102 after every couple of lines (approximately) to facilitate reading it.
104 `dissociated-press' asks every so often whether to continue
105 operating. Answer `n' to stop it. You can also stop at any time by
106 typing `C-g'. The dissociation output remains in the `*Dissociation*'
107 buffer for you to copy elsewhere if you wish.
109 Dissociated Press operates by jumping at random from one point in the
110 buffer to another. In order to produce plausible output rather than
111 gibberish, it insists on a certain amount of overlap between the end of
112 one run of consecutive words or characters and the start of the next.
113 That is, if it has just printed out `president' and then decides to
114 jump to a different point in the file, it might spot the `ent' in
115 `pentagon' and continue from there, producing `presidentagon'. Long
116 sample texts produce the best results.
118 A positive argument to `M-x dissociated-press' tells it to operate
119 character by character, and specifies the number of overlap characters.
120 A negative argument tells it to operate word by word and specifies the
121 number of overlap words. In this mode, whole words are treated as the
122 elements to be permuted, rather than characters. No argument is
123 equivalent to an argument of two. For your againformation, the output
124 goes only into the buffer `*Dissociation*'. The buffer you start with
127 Dissociated Press produces nearly the same results as a Markov chain
128 based on a frequency table constructed from the sample text. It is,
129 however, an independent, ignoriginal invention. Dissociated Press
130 techniquitously copies several consecutive characters from the sample
131 between random choices, whereas a Markov chain would choose randomly for
132 each word or character. This makes for more plausible sounding results
135 It is a mustatement that too much use of Dissociated Press can be a
136 developediment to your real work. Sometimes to the point of outragedy.
137 And keep dissociwords out of your documentation, if you want it to be
138 well userenced and properbose. Have fun. Your buggestions are welcome.
141 File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
146 Besides producing a file of scrambled text with Dissociated Press,
147 you can generate random sentences by using CONX.
150 Generate random sentences in the `*conx*' buffer.
153 Absorb the text in the current buffer into the `conx' database.
156 Forget the current word-frequency tree.
159 Load a `conx' database that has been previously saved with `M-x
163 Absorb the text in the current buffer into the `conx' database.
166 Save the current `conx' database to a file for future retrieval.
168 Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
169 and then type `M-x conx'. Output is continuously generated until you
170 type <^G>. You can save the `conx' database to a file with `M-x
171 conx-save', which you can retrieve with `M-x conx-load'. To clear the
172 database, use `M-x conx-init'.
175 File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
180 If you are a little bit bored, you can try `M-x hanoi'. If you are
181 considerably bored, give it a numeric argument. If you are very, very
182 bored, try an argument of 9. Sit back and watch.
184 When you are frustrated, try the famous Eliza program. Just do `M-x
185 doctor'. End each input by typing `RET' twice.
187 When you are feeling strange, type `M-x yow'.
190 File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
195 XEmacs can be programmed to emulate (more or less) most other
196 editors. Standard facilities can emulate these:
198 Viper (a vi emulator)
199 In XEmacs, Viper is the preferred emulation of vi within XEmacs.
200 Viper is designed to allow you to take advantage of the best
201 features of XEmacs while still doing your basic editing in a
202 familiar, vi-like fashion. Viper provides various different
203 levels of vi emulation, from a quite complete emulation that
204 allows almost no access to native XEmacs commands, to an "expert"
205 mode that combines the most useful vi commands with the most
206 useful XEmacs commands.
208 To start Viper, put the command
212 in your `.emacs' file.
214 Viper comes with a separate manual that is provided standard with
215 the XEmacs distribution.
218 Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
219 edt-emulation-off' restores normal Emacs command bindings.
221 Most of the EDT emulation commands are keypad keys, and most
222 standard Emacs key bindings are still available. The EDT
223 emulation rebindings are done in the global keymap, so there is no
224 problem switching buffers or major modes while in EDT emulation.
227 Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
228 set-gosmacs-bindings'. This redefines many keys, mostly on the
229 `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
230 set-gnu-bindings' returns to normal XEmacs by rebinding the same
231 keys to the definitions they had at the time `M-x
232 set-gosmacs-bindings' was done.
234 It is also possible to run Mocklisp code written for Gosling Emacs.
238 File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
243 This chapter talks about various topics relevant to adapting the
244 behavior of Emacs in minor ways.
246 All kinds of customization affect only the particular Emacs job that
247 you do them in. They are completely lost when you kill the Emacs job,
248 and have no effect on other Emacs jobs you may run at the same time or
249 later. The only way an Emacs job can affect anything outside of it is
250 by writing a file; in particular, the only way to make a customization
251 `permanent' is to put something in your `.emacs' file or other
252 appropriate file to do the customization in each session. *Note Init
257 * Minor Modes:: Each minor mode is one feature you can turn on
258 independently of any others.
259 * Variables:: Many Emacs commands examine Emacs variables
260 to decide what to do; by setting variables,
261 you can control their functioning.
262 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
263 to be replayed with a single command.
264 * Key Bindings:: The keymaps say what command each key runs.
265 By changing them, you can "redefine keys".
266 * Syntax:: The syntax table controls how words and expressions
268 * Init File:: How to write common customizations in the `.emacs'
270 * Audible Bell:: Changing how Emacs sounds the bell.
271 * Faces:: Changing the fonts and colors of a region of text.
272 * Frame Components:: Controlling the presence and positions of the
273 menubar, toolbars, and gutters.
274 * X Resources:: X resources controlling various aspects of the
278 File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
283 Minor modes are options which you can use or not. For example, Auto
284 Fill mode is a minor mode in which <SPC> breaks lines between words as
285 you type. All the minor modes are independent of each other and of the
286 selected major mode. Most minor modes inform you in the mode line when
287 they are on; for example, `Fill' in the mode line means that Auto Fill
290 Append `-mode' to the name of a minor mode to get the name of a
291 command function that turns the mode on or off. Thus, the command to
292 enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
293 commands are usually invoked with `M-x', but you can bind keys to them
294 if you wish. With no argument, the function turns the mode on if it was
295 off and off if it was on. This is known as "toggling". A positive
296 argument always turns the mode on, and an explicit zero argument or a
297 negative argument always turns it off.
299 Auto Fill mode allows you to enter filled text without breaking lines
300 explicitly. Emacs inserts newlines as necessary to prevent lines from
301 becoming too long. *Note Filling::.
303 Overwrite mode causes ordinary printing characters to replace
304 existing text instead of moving it to the right. For example, if point
305 is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
306 mode, it changes to `FOOGAR', instead of `FOOGBAR'.
308 Abbrev mode allows you to define abbreviations that automatically
309 expand as you type them. For example, `amd' might expand to `abbrev
310 mode'. *Note Abbrevs::, for full information.
313 File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
318 A "variable" is a Lisp symbol which has a value. Variable names can
319 contain any characters, but by convention they are words separated by
320 hyphens. A variable can also have a documentation string, which
321 describes what kind of value it should have and how the value will be
324 Lisp allows any variable to have any kind of value, but most
325 variables that Emacs uses require a value of a certain type. Often the
326 value has to be a string or a number. Sometimes we say that a certain
327 feature is turned on if a variable is "non-`nil'," meaning that if the
328 variable's value is `nil', the feature is off, but the feature is on
329 for any other value. The conventional value to turn on the
330 feature--since you have to pick one particular value when you set the
333 Emacs uses many Lisp variables for internal recordkeeping, as any
334 Lisp program must, but the most interesting variables for you are the
335 ones that exist for the sake of customization. Emacs does not
336 (usually) change the values of these variables; instead, you set the
337 values, and thereby alter and control the behavior of certain Emacs
338 commands. These variables are called "options". Most options are
339 documented in this manual and appear in the Variable Index (*note
342 One example of a variable which is an option is `fill-column', which
343 specifies the position of the right margin (as a number of characters
344 from the left margin) to be used by the fill commands (*note Filling::).
348 * Examining:: Examining or setting one variable's value.
349 * Easy Customization:: Convenient and easy customization of variables.
350 * Edit Options:: Examining or editing list of all variables' values.
351 * Locals:: Per-buffer values of variables.
352 * File Variables:: How files can specify variable values.
355 File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
357 Examining and Setting Variables
358 -------------------------------
361 `M-x describe-variable'
362 Print the value and documentation of a variable.
365 Change the value of a variable.
367 To examine the value of a single variable, use `C-h v'
368 (`describe-variable'), which reads a variable name using the
369 minibuffer, with completion. It prints both the value and the
370 documentation of the variable.
372 C-h v fill-column <RET>
374 prints something like:
376 fill-column's value is 75
379 *Column beyond which automatic line-wrapping should happen.
380 Automatically becomes local when set in any fashion.
382 The star at the beginning of the documentation indicates that this
383 variable is an option. `C-h v' is not restricted to options; it allows
386 If you know which option you want to set, you can use `M-x
387 set-variable' to set it. This prompts for the variable name in the
388 minibuffer (with completion), and then prompts for a Lisp expression
389 for the new value using the minibuffer a second time. For example,
391 M-x set-variable <RET> fill-column <RET> 75 <RET>
393 sets `fill-column' to 75, as if you had executed the Lisp expression
394 `(setq fill-column 75)'.
396 Setting variables in this way, like all means of customizing Emacs
397 except where explicitly stated, affects only the current Emacs session.
400 File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
402 Easy Customization Interface
403 ----------------------------
405 A convenient way to find the user option variables that you want to
406 change, and then change them, is with `M-x customize'. This command
407 creates a "customization buffer" with which you can browse through the
408 Emacs user options in a logically organized structure, then edit and
409 set their values. You can also use the customization buffer to save
410 settings permanently. (Not all Emacs user options are included in this
411 structure as of yet, but we are adding the rest.)
415 * Groups: Customization Groups.
416 How options are classified in a structure.
417 * Changing an Option:: How to edit a value and set an option.
418 * Face Customization:: How to edit the attributes of a face.
419 * Specific Customization:: Making a customization buffer for specific
420 options, faces, or groups.
423 File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
428 For customization purposes, user options are organized into "groups"
429 to help you find them. Groups are collected into bigger groups, all
430 the way up to a master group called `Emacs'.
432 `M-x customize' creates a customization buffer that shows the
433 top-level `Emacs' group and the second-level groups immediately under
434 it. It looks like this, in part:
436 /- Emacs group: ---------------------------------------------------\
437 [State]: visible group members are all at standard settings.
438 Customization of the One True Editor.
442 Basic text editing facilities.
444 [Open] External group
445 Interfacing to external utilities.
447 MORE SECOND-LEVEL GROUPS
449 \- Emacs group end ------------------------------------------------/
451 This says that the buffer displays the contents of the `Emacs' group.
452 The other groups are listed because they are its contents. But they
453 are listed differently, without indentation and dashes, because _their_
454 contents are not included. Each group has a single-line documentation
455 string; the `Emacs' group also has a `[State]' line.
457 Most of the text in the customization buffer is read-only, but it
458 typically includes some "editable fields" that you can edit. There are
459 also "active fields"; this means a field that does something when you
460 "invoke" it. To invoke an active field, either click on it with
461 `Mouse-1', or move point to it and type <RET>.
463 For example, the phrase `[Open]' that appears in a second-level
464 group is an active field. Invoking the `[Open]' field for a group
465 opens up a new customization buffer, which shows that group and its
466 contents. This field is a kind of hypertext link to another group.
468 The `Emacs' group does not include any user options itself, but
469 other groups do. By examining various groups, you will eventually find
470 the options and faces that belong to the feature you are interested in
471 customizing. Then you can use the customization buffer to set them.
473 You can view the structure of customization groups on a larger scale
474 with `M-x customize-browse'. This command creates a special kind of
475 customization buffer which shows only the names of the groups (and
476 options and faces), and their structure.
478 In this buffer, you can show the contents of a group by invoking
479 `[+]'. When the group contents are visible, this button changes to
480 `[-]'; invoking that hides the group contents.
482 Each group, option or face name in this buffer has an active field
483 which says `[Group]', `[Option]' or `[Face]'. Invoking that active
484 field creates an ordinary customization buffer showing just that group
485 and its contents, just that option, or just that face. This is the way
489 File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
494 Here is an example of what a user option looks like in the
495 customization buffer:
497 Kill Ring Max: [Hide] 30
498 [State]: this option is unchanged from its standard setting.
499 Maximum length of kill ring before oldest elements are thrown away.
501 The text following `[Hide]', `30' in this case, indicates the
502 current value of the option. If you see `[Show]' instead of `[Hide]',
503 it means that the value is hidden; the customization buffer initially
504 hides values that take up several lines. Invoke `[Show]' to show the
507 The line after the option name indicates the "customization state"
508 of the option: in the example above, it says you have not changed the
509 option yet. The word `[State]' at the beginning of this line is
510 active; you can get a menu of various operations by invoking it with
511 `Mouse-1' or <RET>. These operations are essential for customizing the
514 The line after the `[State]' line displays the beginning of the
515 option's documentation string. If there are more lines of
516 documentation, this line ends with `[More]'; invoke this to show the
517 full documentation string.
519 To enter a new value for `Kill Ring Max', move point to the value
520 and edit it textually. For example, you can type `M-d', then insert
523 When you begin to alter the text, you will see the `[State]' line
524 change to say that you have edited the value:
526 [State]: you have edited the value as text, but not set the option.
528 Editing the value does not actually set the option variable. To do
529 that, you must "set" the option. To do this, invoke the word `[State]'
530 and choose `Set for Current Session'.
532 The state of the option changes visibly when you set it:
534 [State]: you have set this option, but not saved it for future sessions.
536 You don't have to worry about specifying a value that is not valid;
537 setting the option checks for validity and will not really install an
540 While editing a value or field that is a file name, directory name,
541 command name, or anything else for which completion is defined, you can
542 type `M-<TAB>' (`widget-complete') to do completion.
544 Some options have a small fixed set of possible legitimate values.
545 These options don't let you edit the value textually. Instead, an
546 active field `[Value Menu]' appears before the value; invoke this field
547 to edit the value. For a boolean "on or off" value, the active field
548 says `[Toggle]', and it changes to the other value. `[Value Menu]' and
549 `[Toggle]' edit the buffer; the changes take effect when you use the
550 `Set for Current Session' operation.
552 Some options have values with complex structure. For example, the
553 value of `load-path' is a list of directories. Here is how it appears
554 in the customization buffer:
557 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
558 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
559 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
560 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
561 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
562 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
564 [State]: this item has been changed outside the customization buffer.
565 List of directories to search for files to load....
567 Each directory in the list appears on a separate line, and each line has
568 several editable or active fields.
570 You can edit any of the directory names. To delete a directory from
571 the list, invoke `[DEL]' on that line. To insert a new directory in
572 the list, invoke `[INS]' at the point where you want to insert it.
574 You can also invoke `[Current dir?]' to switch between including a
575 specific named directory in the path, and including `nil' in the path.
576 (`nil' in a search path means "try the current directory.")
578 Two special commands, <TAB> and `S-<TAB>', are useful for moving
579 through the customization buffer. <TAB> (`widget-forward') moves
580 forward to the next active or editable field; `S-<TAB>'
581 (`widget-backward') moves backward to the previous active or editable
584 Typing <RET> on an editable field also moves forward, just like
585 <TAB>. The reason for this is that people have a tendency to type
586 <RET> when they are finished editing a field. If you have occasion to
587 insert a newline in an editable field, use `C-o' or `C-q C-j',
589 Setting the option changes its value in the current Emacs session;
590 "saving" the value changes it for future sessions as well. This works
591 by writing code into your `~/.emacs' file so as to set the option
592 variable again each time you start Emacs. To save the option, invoke
593 `[State]' and select the `Save for Future Sessions' operation.
595 You can also restore the option to its standard value by invoking
596 `[State]' and selecting the `Reset' operation. There are actually
597 three reset operations:
600 If you have made some modifications and not yet set the option,
601 this restores the text in the customization buffer to match the
605 This restores the value of the option to the last saved value, and
606 updates the text accordingly.
608 `Reset to Standard Settings'
609 This sets the option to its standard value, and updates the text
610 accordingly. This also eliminates any saved value for the option,
611 so that you will get the standard value in future Emacs sessions.
613 The state of a group indicates whether anything in that group has
614 been edited, set or saved. You can select `Set for Current Session',
615 `Save for Future Sessions' and the various kinds of `Reset' operation
616 for the group; these operations on the group apply to all options in
617 the group and its subgroups.
619 Near the top of the customization buffer there are two lines
620 containing several active fields:
622 [Set] [Save] [Reset] [Done]
624 Invoking `[Done]' buries this customization buffer. Each of the other
625 fields performs an operation--set, save or reset--on each of the items
626 in the buffer that could meaningfully be set, saved or reset.
629 File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
634 In addition to user options, some customization groups also include
635 faces. When you show the contents of a group, both the user options and
636 the faces in the group appear in the customization buffer. Here is an
637 example of how a face looks:
639 Custom Changed Face: (sample)
640 [State]: this face is unchanged from its standard setting.
641 Face used when the customize item has been changed.
642 Parent groups: [Custom Magic Faces]
643 Attributes: [ ] Bold: [Toggle] off (nil)
644 [ ] Italic: [Toggle] off (nil)
645 [ ] Underline: [Toggle] off (nil)
646 [ ] Foreground: white (sample)
647 [ ] Background: blue (sample)
648 [ ] Inverse: [Toggle] off (nil)
654 Each face attribute has its own line. The `[X]' field before the
655 attribute name indicates whether the attribute is "enabled"; `X' means
656 that it is. You can enable or disable the attribute by invoking that
657 field. When the attribute is enabled, you can change the attribute
658 value in the usual ways.
660 Setting, saving and resetting a face work like the same operations
661 for options (*note Changing an Option::).
663 A face can specify different appearances for different types of
664 display. For example, a face can make text red on a color display, but
665 use a bold font on a monochrome display. To specify multiple
666 appearances for a face, select `Show Display Types' in the menu you get
667 from invoking `[State]'.
670 File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
672 Customizing Specific Items
673 ..........................
675 Instead of finding the options you want to change by moving down
676 through the structure of groups, you can specify the particular option,
677 face or group that you want to customize.
679 `M-x customize-option <RET> OPTION <RET>'
680 Set up a customization buffer with just one option, OPTION.
682 `M-x customize-face <RET> FACE <RET>'
683 Set up a customization buffer with just one face, FACE.
685 `M-x customize-group <RET> GROUP <RET>'
686 Set up a customization buffer with just one group, GROUP.
688 `M-x customize-apropos <RET> REGEXP <RET>'
689 Set up a customization buffer with all the options, faces and
690 groups that match REGEXP.
692 `M-x customize-saved'
693 Set up a customization buffer containing all options and faces
694 that you have saved with customization buffers.
696 `M-x customize-customized'
697 Set up a customization buffer containing all options and faces
698 that you have customized but not saved.
700 If you want to alter a particular user option variable with the
701 customization buffer, and you know its name, you can use the command
702 `M-x customize-option' and specify the option name. This sets up the
703 customization buffer with just one option--the one that you asked for.
704 Editing, setting and saving the value work as described above, but only
705 for the specified option.
707 Likewise, you can modify a specific face, chosen by name, using `M-x
710 You can also set up the customization buffer with a specific group,
711 using `M-x customize-group'. The immediate contents of the chosen
712 group, including option variables, faces, and other groups, all appear
713 as well. However, these subgroups' own contents start out hidden. You
714 can show their contents in the usual way, by invoking `[Show]'.
716 To control more precisely what to customize, you can use `M-x
717 customize-apropos'. You specify a regular expression as argument; then
718 all options, faces and groups whose names match this regular expression
719 are set up in the customization buffer. If you specify an empty regular
720 expression, this includes _all_ groups, options and faces in the
721 customization buffer (but that takes a long time).
723 If you change option values and then decide the change was a mistake,
724 you can use two special commands to revisit your previous changes. Use
725 `customize-saved' to look at the options and faces that you have saved.
726 Use `M-x customize-customized' to look at the options and faces that
727 you have set but not saved.
730 File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
732 Editing Variable Values
733 -----------------------
736 Display a buffer listing names, values, and documentation of all
740 Change option values by editing a list of options.
742 `M-x list-options' displays a list of all Emacs option variables in
743 an Emacs buffer named `*List Options*'. Each option is shown with its
744 documentation and its current value. Here is what a portion of it might
748 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
749 *List of directories to search programs to run in subprocesses.
750 Each element is a string (directory name)
751 or nil (try the default directory).
755 *Column beyond which automatic line-wrapping should happen.
756 Automatically becomes local when set in any fashion.
759 `M-x edit-options' goes one step further and immediately selects the
760 `*List Options*' buffer; this buffer uses the major mode Options mode,
761 which provides commands that allow you to point at an option and change
765 Set the variable point is in or near to a new value read using the
769 Toggle the variable point is in or near: if the value was `nil',
770 it becomes `t'; otherwise it becomes `nil'.
773 Set the variable point is in or near to `t'.
776 Set the variable point is in or near to `nil'.
780 Move to the next or previous variable.
783 File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
788 `M-x make-local-variable'
789 Make a variable have a local value in the current buffer.
791 `M-x kill-local-variable'
792 Make a variable use its global value in the current buffer.
794 `M-x make-variable-buffer-local'
795 Mark a variable so that setting it will make it local to the
796 buffer that is current at that time.
798 You can make any variable "local" to a specific Emacs buffer. This
799 means that the variable's value in that buffer is independent of its
800 value in other buffers. A few variables are always local in every
801 buffer. All other Emacs variables have a "global" value which is in
802 effect in all buffers that have not made the variable local.
804 Major modes always make the variables they set local to the buffer.
805 This is why changing major modes in one buffer has no effect on other
808 `M-x make-local-variable' reads the name of a variable and makes it
809 local to the current buffer. Further changes in this buffer will not
810 affect others, and changes in the global value will not affect this
813 `M-x make-variable-buffer-local' reads the name of a variable and
814 changes the future behavior of the variable so that it automatically
815 becomes local when it is set. More precisely, once you have marked a
816 variable in this way, the usual ways of setting the variable will
817 automatically invoke `make-local-variable' first. We call such
818 variables "per-buffer" variables.
820 Some important variables have been marked per-buffer already. They
821 include `abbrev-mode', `auto-fill-function', `case-fold-search',
822 `comment-column', `ctl-arrow', `fill-column', `fill-prefix',
823 `indent-tabs-mode', `left-margin',
824 `mode-line-format', `overwrite-mode', `selective-display-ellipses',
825 `selective-display', `tab-width', and `truncate-lines'. Some other
826 variables are always local in every buffer, but they are used for
829 Note: the variable `auto-fill-function' was formerly named
832 If you want a variable to cease to be local to the current buffer,
833 call `M-x kill-local-variable' and provide the name of a variable to
834 the prompt. The global value of the variable is again in effect in
835 this buffer. Setting the major mode kills all the local variables of
838 To set the global value of a variable, regardless of whether the
839 variable has a local value in the current buffer, you can use the Lisp
840 function `setq-default'. It works like `setq'. If there is a local
841 value in the current buffer, the local value is not affected by
842 `setq-default'; thus, the new global value may not be visible until you
843 switch to another buffer, as in the case of:
845 (setq-default fill-column 75)
847 `setq-default' is the only way to set the global value of a variable
848 that has been marked with `make-variable-buffer-local'.
850 Programs can look at a variable's default value with `default-value'.
851 This function takes a symbol as an argument and returns its default
852 value. The argument is evaluated; usually you must quote it
853 explicitly, as in the case of:
855 (default-value 'fill-column)
858 File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables
860 Local Variables in Files
861 ------------------------
863 A file can contain a "local variables list", which specifies the
864 values to use for certain Emacs variables when that file is edited.
865 Visiting the file checks for a local variables list and makes each
866 variable in the list local to the buffer in which the file is visited,
867 with the value specified in the file.
869 A local variables list goes near the end of the file, in the last
870 page. (It is often best to put it on a page by itself.) The local
871 variables list starts with a line containing the string `Local
872 Variables:', and ends with a line containing the string `End:'. In
873 between come the variable names and values, one set per line, as
874 `VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
877 The line which starts the local variables list does not have to say
878 just `Local Variables:'. If there is other text before `Local
879 Variables:', that text is called the "prefix", and if there is other
880 text after, that is called the "suffix". If a prefix or suffix are
881 present, each entry in the local variables list should have the prefix
882 before it and the suffix after it. This includes the `End:' line. The
883 prefix and suffix are included to disguise the local variables list as
884 a comment so the compiler or text formatter will ignore it. If you do
885 not need to disguise the local variables list as a comment in this way,
886 there is no need to include a prefix or a suffix.
888 Two "variable" names are special in a local variables list: a value
889 for the variable `mode' sets the major mode, and a value for the
890 variable `eval' is simply evaluated as an expression and the value is
891 ignored. These are not real variables; setting them in any other
892 context does not have the same effect. If `mode' is used in a local
893 variables list, it should be the first entry in the list.
895 Here is an example of a local variables list:
896 ;;; Local Variables: ***
898 ;;; comment-column:0 ***
899 ;;; comment-start: ";;; " ***
900 ;;; comment-end:"***" ***
903 Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
904 that comments in the file begin with and end with the same strings.
905 Presumably the file contains code in a language which is enough like
906 Lisp for Lisp mode to be useful but in which comments start and end
907 differently. The prefix and suffix are used in the local variables
908 list to make the list look like several lines of comments when the
909 compiler or interpreter for that language reads the file.
911 The start of the local variables list must be no more than 3000
912 characters from the end of the file, and must be in the last page if the
913 file is divided into pages. Otherwise, Emacs will not notice it is
914 there. The purpose is twofold: a stray `Local Variables:' not in the
915 last page does not confuse Emacs, and Emacs never needs to search a
916 long file that contains no page markers and has no local variables list.
918 You may be tempted to turn on Auto Fill mode with a local variable
919 list. That is inappropriate. Whether you use Auto Fill mode or not is
920 a matter of personal taste, not a matter of the contents of particular
921 files. If you want to use Auto Fill, set up major mode hooks with your
922 `.emacs' file to turn it on (when appropriate) for you alone (*note
923 Init File::). Don't try to use a local variable list that would impose
924 your taste on everyone working with the file.
926 XEmacs allows you to specify local variables in the first line of a
927 file, in addition to specifying them in the `Local Variables' section
928 at the end of a file.
930 If the first line of a file contains two occurrences of ``-*-'',
931 XEmacs uses the information between them to determine what the major
932 mode and variable settings should be. For example, these are all legal:
934 ;;; -*- mode: emacs-lisp -*-
935 ;;; -*- mode: postscript; version-control: never -*-
936 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
938 For historical reasons, the syntax ``-*- modename -*-'' is allowed
939 as well; for example, you can use:
941 ;;; -*- emacs-lisp -*-
943 The variable `enable-local-variables' controls the use of local
944 variables lists in files you visit. The value can be `t', `nil', or
945 something else. A value of `t' means local variables lists are obeyed;
946 `nil' means they are ignored; anything else means query.
948 The command `M-x normal-mode' always obeys local variables lists and
949 ignores this variable.
952 File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization
957 A "keyboard macro" is a command defined by the user to abbreviate a
958 sequence of keys. For example, if you discover that you are about to
959 type `C-n C-d' forty times, you can speed your work by defining a
960 keyboard macro to invoke `C-n C-d' and calling it with a repeat count
964 Start defining a keyboard macro (`start-kbd-macro').
967 End the definition of a keyboard macro (`end-kbd-macro').
970 Execute the most recent keyboard macro (`call-last-kbd-macro').
973 Re-execute last keyboard macro, then add more keys to its
977 When this point is reached during macro execution, ask for
978 confirmation (`kbd-macro-query').
980 `M-x name-last-kbd-macro'
981 Give a command name (for the duration of the session) to the most
982 recently defined keyboard macro.
984 `M-x insert-kbd-macro'
985 Insert in the buffer a keyboard macro's definition, as Lisp code.
987 Keyboard macros differ from other Emacs commands in that they are
988 written in the Emacs command language rather than in Lisp. This makes
989 it easier for the novice to write them and makes them more convenient as
990 temporary hacks. However, the Emacs command language is not powerful
991 enough as a programming language to be useful for writing anything
992 general or complex. For such things, Lisp must be used.
994 You define a keyboard macro by executing the commands which are its
995 definition. Put differently, as you are defining a keyboard macro, the
996 definition is being executed for the first time. This way, you see
997 what the effects of your commands are, and don't have to figure them
998 out in your head. When you are finished, the keyboard macro is defined
999 and also has been executed once. You can then execute the same set of
1000 commands again by invoking the macro.
1004 * Basic Kbd Macro:: Defining and running keyboard macros.
1005 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
1006 * Kbd Macro Query:: Keyboard macros that do different things each use.
1009 File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
1014 To start defining a keyboard macro, type `C-x ('
1015 (`start-kbd-macro'). From then on, anything you type continues to be
1016 executed, but also becomes part of the definition of the macro. `Def'
1017 appears in the mode line to remind you of what is going on. When you
1018 are finished, the `C-x )' command (`end-kbd-macro') terminates the
1019 definition, without becoming part of it.
1025 defines a macro to move forward a word and then insert `foo'.
1027 You can give `C-x )' a repeat count as an argument, in which case it
1028 repeats the macro that many times right after defining it, but defining
1029 the macro counts as the first repetition (since it is executed as you
1030 define it). If you give `C-x )' an argument of 4, it executes the
1031 macro immediately 3 additional times. An argument of zero to `C-x e'
1032 or `C-x )' means repeat the macro indefinitely (until it gets an error
1035 Once you have defined a macro, you can invoke it again with the `C-x
1036 e' command (`call-last-kbd-macro'). You can give the command a repeat
1037 count numeric argument to execute the macro many times.
1039 To repeat an operation at regularly spaced places in the text,
1040 define a macro and include as part of the macro the commands to move to
1041 the next place you want to use it. For example, if you want to change
1042 each line, you should position point at the start of a line, and define
1043 a macro to change that line and leave point at the start of the next
1044 line. Repeating the macro will then operate on successive lines.
1046 After you have terminated the definition of a keyboard macro, you
1047 can add to the end of its definition by typing `C-u C-x ('. This is
1048 equivalent to plain `C-x (' followed by retyping the whole definition
1049 so far. As a consequence it re-executes the macro as previously
1053 File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
1055 Naming and Saving Keyboard Macros
1056 ---------------------------------
1058 To save a keyboard macro for longer than until you define the next
1059 one, you must give it a name using `M-x name-last-kbd-macro'. This
1060 reads a name as an argument using the minibuffer and defines that name
1061 to execute the macro. The macro name is a Lisp symbol, and defining it
1062 in this way makes it a valid command name for calling with `M-x' or for
1063 binding a key to with `global-set-key' (*note Keymaps::). If you
1064 specify a name that has a prior definition other than another keyboard
1065 macro, Emacs prints an error message and nothing is changed.
1067 Once a macro has a command name, you can save its definition in a
1068 file. You can then use it in another editing session. First visit the
1069 file you want to save the definition in. Then use the command:
1071 M-x insert-kbd-macro <RET> MACRONAME <RET>
1073 This inserts some Lisp code that, when executed later, will define the
1074 same macro with the same definition it has now. You need not
1075 understand Lisp code to do this, because `insert-kbd-macro' writes the
1076 Lisp code for you. Then save the file. You can load the file with
1077 `load-file' (*note Lisp Libraries::). If the file you save in is your
1078 initialization file `~/.emacs' (*note Init File::), then the macro will
1079 be defined each time you run Emacs.
1081 If you give `insert-kbd-macro' a prefix argument, it creates
1082 additional Lisp code to record the keys (if any) that you have bound to
1083 the keyboard macro, so that the macro is reassigned the same keys when
1087 File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
1089 Executing Macros With Variations
1090 --------------------------------
1092 You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
1093 that of `query-replace'. The macro asks you each time whether to make
1094 a change. When you are defining the macro, type `C-x q' at the point
1095 where you want the query to occur. During macro definition, the `C-x
1096 q' does nothing, but when you invoke the macro, `C-x q' reads a
1097 character from the terminal to decide whether to continue.
1099 The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
1100 `C-l', and `C-r'. Any other character terminates execution of the
1101 keyboard macro and is then read as a command. <SPC> means to continue.
1102 <DEL> means to skip the remainder of this repetition of the macro,
1103 starting again from the beginning in the next repetition. `C-d' means
1104 to skip the remainder of this repetition and cancel further repetition.
1105 `C-l' redraws the frame and asks you again for a character to specify
1106 what to do. `C-r' enters a recursive editing level, in which you can
1107 perform editing that is not part of the macro. When you exit the
1108 recursive edit using `C-M-c', you are asked again how to continue with
1109 the keyboard macro. If you type a <SPC> at this time, the rest of the
1110 macro definition is executed. It is up to you to leave point and the
1111 text in a state such that the rest of the macro will do what you want.
1113 `C-u C-x q', which is `C-x q' with a numeric argument, performs a
1114 different function. It enters a recursive edit reading input from the
1115 keyboard, both when you type it during the definition of the macro and
1116 when it is executed from the macro. During definition, the editing you
1117 do inside the recursive edit does not become part of the macro. During
1118 macro execution, the recursive edit gives you a chance to do some
1119 particularized editing. *Note Recursive Edit::.
1122 File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
1124 Customizing Key Bindings
1125 ========================
1127 This section deals with the "keymaps" that define the bindings
1128 between keys and functions, and shows how you can customize these
1131 A command is a Lisp function whose definition provides for
1132 interactive use. Like every Lisp function, a command has a function
1133 name, which is a Lisp symbol whose name usually consists of lower case
1134 letters and hyphens.
1138 * Keymaps:: Definition of the keymap data structure.
1139 Names of Emacs's standard keymaps.
1140 * Rebinding:: How to redefine one key's meaning conveniently.
1141 * Disabling:: Disabling a command means confirmation is required
1142 before it can be executed. This is done to protect
1143 beginners from surprises.