2 @node Customization, Quitting, Emulation, Top
6 This chapter talks about various topics relevant to adapting the
7 behavior of Emacs in minor ways.
9 All kinds of customization affect only the particular Emacs job that you
10 do them in. They are completely lost when you kill the Emacs job, and
11 have no effect on other Emacs jobs you may run at the same time or
12 later. The only way an Emacs job can affect anything outside of it is
13 by writing a file; in particular, the only way to make a customization
14 `permanent' is to put something in your init file or other appropriate
15 file to do the customization in each session. @xref{Init File}.
18 * Minor Modes:: Each minor mode is one feature you can turn on
19 independently of any others.
20 * Variables:: Many Emacs commands examine Emacs variables
21 to decide what to do; by setting variables,
22 you can control their functioning.
23 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
24 to be replayed with a single command.
25 * Key Bindings:: The keymaps say what command each key runs.
26 By changing them, you can "redefine keys".
27 * Syntax:: The syntax table controls how words and expressions
29 * Init File:: How to write common customizations in the init file.
30 * Audible Bell:: Changing how Emacs sounds the bell.
31 * Faces:: Changing the fonts and colors of a region of text.
32 * Frame Components:: Controlling the presence and positions of the
33 menubar, toolbars, and gutters.
34 * X Resources:: X resources controlling various aspects of the
43 Minor modes are options which you can use or not. For example, Auto
44 Fill mode is a minor mode in which @key{SPC} breaks lines between words
45 as you type. All the minor modes are independent of each other and of
46 the selected major mode. Most minor modes inform you in the mode line
47 when they are on; for example, @samp{Fill} in the mode line means that
50 Append @code{-mode} to the name of a minor mode to get the name of a
51 command function that turns the mode on or off. Thus, the command to
52 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
53 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
54 if you wish. With no argument, the function turns the mode on if it was
55 off and off if it was on. This is known as @dfn{toggling}. A positive
56 argument always turns the mode on, and an explicit zero argument or a
57 negative argument always turns it off.
59 @cindex Auto Fill mode
60 @findex auto-fill-mode
61 Auto Fill mode allows you to enter filled text without breaking lines
62 explicitly. Emacs inserts newlines as necessary to prevent lines from
63 becoming too long. @xref{Filling}.
65 @cindex Overwrite mode
66 @findex overwrite-mode
67 Overwrite mode causes ordinary printing characters to replace existing
68 text instead of moving it to the right. For example, if point is in
69 front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite
70 mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill
74 Abbrev mode allows you to define abbreviations that automatically expand
75 as you type them. For example, @samp{amd} might expand to @samp{abbrev
76 mode}. @xref{Abbrevs}, for full information.
83 A @dfn{variable} is a Lisp symbol which has a value. Variable names
84 can contain any characters, but by convention they are words separated
85 by hyphens. A variable can also have a documentation string, which
86 describes what kind of value it should have and how the value will be
89 Lisp allows any variable to have any kind of value, but most variables
90 that Emacs uses require a value of a certain type. Often the value has
91 to be a string or a number. Sometimes we say that a certain feature is
92 turned on if a variable is ``non-@code{nil},'' meaning that if the
93 variable's value is @code{nil}, the feature is off, but the feature is
94 on for @i{any} other value. The conventional value to turn on the
95 feature---since you have to pick one particular value when you set the
96 variable---is @code{t}.
98 Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
99 program must, but the most interesting variables for you are the ones that
100 exist for the sake of customization. Emacs does not (usually) change the
101 values of these variables; instead, you set the values, and thereby alter
102 and control the behavior of certain Emacs commands. These variables are
103 called @dfn{options}. Most options are documented in this manual and
104 appear in the Variable Index (@pxref{Variable Index}).
106 One example of a variable which is an option is @code{fill-column}, which
107 specifies the position of the right margin (as a number of characters from
108 the left margin) to be used by the fill commands (@pxref{Filling}).
111 * Examining:: Examining or setting one variable's value.
112 * Easy Customization:: Convenient and easy customization of variables.
113 * Edit Options:: Examining or editing list of all variables' values.
114 * Locals:: Per-buffer values of variables.
115 * File Variables:: How files can specify variable values.
119 @subsection Examining and Setting Variables
120 @cindex setting variables
124 @itemx M-x describe-variable
125 Print the value and documentation of a variable.
127 @item M-x set-variable
128 Change the value of a variable.
132 @findex describe-variable
133 To examine the value of a single variable, use @kbd{C-h v}
134 (@code{describe-variable}), which reads a variable name using the
135 minibuffer, with completion. It prints both the value and the
136 documentation of the variable.
139 C-h v fill-column @key{RET}
143 prints something like:
146 fill-column's value is 75
149 *Column beyond which automatic line-wrapping should happen.
150 Automatically becomes local when set in any fashion.
155 The star at the beginning of the documentation indicates that this variable
156 is an option. @kbd{C-h v} is not restricted to options; it allows any
160 If you know which option you want to set, you can use @kbd{M-x
161 set-variable} to set it. This prompts for the variable name in the
162 minibuffer (with completion), and then prompts for a Lisp expression for the
163 new value using the minibuffer a second time. For example,
166 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
170 sets @code{fill-column} to 75, as if you had executed the Lisp expression
171 @code{(setq fill-column 75)}.
173 Setting variables in this way, like all means of customizing Emacs
174 except where explicitly stated, affects only the current Emacs session.
176 @node Easy Customization
177 @subsection Easy Customization Interface
180 @cindex customization buffer
181 A convenient way to find the user option variables that you want to
182 change, and then change them, is with @kbd{M-x customize}. This command
183 creates a @dfn{customization buffer} with which you can browse through
184 the Emacs user options in a logically organized structure, then edit and
185 set their values. You can also use the customization buffer to save
186 settings permanently. (Not all Emacs user options are included in this
187 structure as of yet, but we are adding the rest.)
190 * Groups: Customization Groups.
191 How options are classified in a structure.
192 * Changing an Option:: How to edit a value and set an option.
193 * Face Customization:: How to edit the attributes of a face.
194 * Specific Customization:: Making a customization buffer for specific
195 options, faces, or groups.
198 @node Customization Groups
199 @subsubsection Customization Groups
200 @cindex customization groups
202 For customization purposes, user options are organized into
203 @dfn{groups} to help you find them. Groups are collected into bigger
204 groups, all the way up to a master group called @code{Emacs}.
206 @kbd{M-x customize} creates a customization buffer that shows the
207 top-level @code{Emacs} group and the second-level groups immediately
208 under it. It looks like this, in part:
211 /- Emacs group: ---------------------------------------------------\
212 [State]: visible group members are all at standard settings.
213 Customization of the One True Editor.
217 Basic text editing facilities.
219 [Open] External group
220 Interfacing to external utilities.
222 @var{more second-level groups}
224 \- Emacs group end ------------------------------------------------/
229 This says that the buffer displays the contents of the @code{Emacs}
230 group. The other groups are listed because they are its contents. But
231 they are listed differently, without indentation and dashes, because
232 @emph{their} contents are not included. Each group has a single-line
233 documentation string; the @code{Emacs} group also has a @samp{[State]}
236 @cindex editable fields (customization buffer)
237 @cindex active fields (customization buffer)
238 Most of the text in the customization buffer is read-only, but it
239 typically includes some @dfn{editable fields} that you can edit. There
240 are also @dfn{active fields}; this means a field that does something
241 when you @dfn{invoke} it. To invoke an active field, either click on it
242 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
244 For example, the phrase @samp{[Open]} that appears in a second-level
245 group is an active field. Invoking the @samp{[Open]} field for a group
246 opens up a new customization buffer, which shows that group and its
247 contents. This field is a kind of hypertext link to another group.
249 The @code{Emacs} group does not include any user options itself, but
250 other groups do. By examining various groups, you will eventually find
251 the options and faces that belong to the feature you are interested in
252 customizing. Then you can use the customization buffer to set them.
254 @findex customize-browse
255 You can view the structure of customization groups on a larger scale
256 with @kbd{M-x customize-browse}. This command creates a special kind of
257 customization buffer which shows only the names of the groups (and
258 options and faces), and their structure.
260 In this buffer, you can show the contents of a group by invoking
261 @samp{[+]}. When the group contents are visible, this button changes to
262 @samp{[-]}; invoking that hides the group contents.
264 Each group, option or face name in this buffer has an active field
265 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
266 that active field creates an ordinary customization buffer showing just
267 that group and its contents, just that option, or just that face.
268 This is the way to set values in it.
270 @node Changing an Option
271 @subsubsection Changing an Option
273 Here is an example of what a user option looks like in the
274 customization buffer:
277 Kill Ring Max: [Hide] 30
278 [State]: this option is unchanged from its standard setting.
279 Maximum length of kill ring before oldest elements are thrown away.
282 The text following @samp{[Hide]}, @samp{30} in this case, indicates
283 the current value of the option. If you see @samp{[Show]} instead of
284 @samp{[Hide]}, it means that the value is hidden; the customization
285 buffer initially hides values that take up several lines. Invoke
286 @samp{[Show]} to show the value.
288 The line after the option name indicates the @dfn{customization state}
289 of the option: in the example above, it says you have not changed the
290 option yet. The word @samp{[State]} at the beginning of this line is
291 active; you can get a menu of various operations by invoking it with
292 @kbd{Mouse-1} or @key{RET}. These operations are essential for
293 customizing the variable.
295 The line after the @samp{[State]} line displays the beginning of the
296 option's documentation string. If there are more lines of
297 documentation, this line ends with @samp{[More]}; invoke this to show
298 the full documentation string.
300 To enter a new value for @samp{Kill Ring Max}, move point to the value
301 and edit it textually. For example, you can type @kbd{M-d}, then insert
304 When you begin to alter the text, you will see the @samp{[State]} line
305 change to say that you have edited the value:
308 [State]: you have edited the value as text, but not set the option.
311 @cindex setting option value
312 Editing the value does not actually set the option variable. To do
313 that, you must @dfn{set} the option. To do this, invoke the word
314 @samp{[State]} and choose @samp{Set for Current Session}.
316 The state of the option changes visibly when you set it:
319 [State]: you have set this option, but not saved it for future sessions.
322 You don't have to worry about specifying a value that is not valid;
323 setting the option checks for validity and will not really install an
326 @kindex M-TAB @r{(customization buffer)}
327 @findex widget-complete
328 While editing a value or field that is a file name, directory name,
329 command name, or anything else for which completion is defined, you can
330 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
332 Some options have a small fixed set of possible legitimate values.
333 These options don't let you edit the value textually. Instead, an
334 active field @samp{[Value Menu]} appears before the value; invoke this
335 field to edit the value. For a boolean ``on or off'' value, the active
336 field says @samp{[Toggle]}, and it changes to the other value.
337 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
338 take effect when you use the @samp{Set for Current Session} operation.
340 Some options have values with complex structure. For example, the
341 value of @code{load-path} is a list of directories. Here is how it
342 appears in the customization buffer:
346 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
347 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
348 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
349 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
350 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
351 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
353 [State]: this item has been changed outside the customization buffer.
354 List of directories to search for files to load....
358 Each directory in the list appears on a separate line, and each line has
359 several editable or active fields.
361 You can edit any of the directory names. To delete a directory from
362 the list, invoke @samp{[DEL]} on that line. To insert a new directory in
363 the list, invoke @samp{[INS]} at the point where you want to insert it.
365 You can also invoke @samp{[Current dir?]} to switch between including
366 a specific named directory in the path, and including @code{nil} in the
367 path. (@code{nil} in a search path means ``try the current
370 @kindex TAB @r{(customization buffer)}
371 @kindex S-TAB @r{(customization buffer)}
372 @findex widget-forward
373 @findex widget-backward
374 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
375 moving through the customization buffer. @key{TAB}
376 (@code{widget-forward}) moves forward to the next active or editable
377 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
378 previous active or editable field.
380 Typing @key{RET} on an editable field also moves forward, just like
381 @key{TAB}. The reason for this is that people have a tendency to type
382 @key{RET} when they are finished editing a field. If you have occasion
383 to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
386 @cindex saving option value
387 Setting the option changes its value in the current Emacs session;
388 @dfn{saving} the value changes it for future sessions as well. This
389 works by writing code into your init file so as to set the option
390 variable again each time you start Emacs. @xref{Init File}. To save
391 the option, invoke @samp{[State]} and select the @samp{Save for Future
394 You can also restore the option to its standard value by invoking
395 @samp{[State]} and selecting the @samp{Reset} operation. There are
396 actually three reset operations:
399 @item Reset to Current
400 If you have made some modifications and not yet set the option,
401 this restores the text in the customization buffer to match
405 This restores the value of the option to the last saved value,
406 and updates the text accordingly.
408 @item Reset to Standard Settings
409 This sets the option to its standard value, and updates the text
410 accordingly. This also eliminates any saved value for the option,
411 so that you will get the standard value in future Emacs sessions.
414 The state of a group indicates whether anything in that group has been
415 edited, set or saved. You can select @samp{Set for Current Session},
416 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
417 operation for the group; these operations on the group apply to all
418 options in the group and its subgroups.
420 Near the top of the customization buffer there are two lines
421 containing several active fields:
424 [Set] [Save] [Reset] [Done]
428 Invoking @samp{[Done]} buries this customization buffer. Each of the
429 other fields performs an operation---set, save or reset---on each of the
430 items in the buffer that could meaningfully be set, saved or reset.
432 @node Face Customization
433 @subsubsection Customizing Faces
434 @cindex customizing faces
437 @cindex fonts and faces
439 In addition to user options, some customization groups also include
440 faces. When you show the contents of a group, both the user options and
441 the faces in the group appear in the customization buffer. Here is an
442 example of how a face looks:
445 Custom Changed Face: (sample)
446 [State]: this face is unchanged from its standard setting.
447 Face used when the customize item has been changed.
448 Parent groups: [Custom Magic Faces]
449 Attributes: [ ] Bold: [Toggle] off (nil)
450 [ ] Italic: [Toggle] off (nil)
451 [ ] Underline: [Toggle] off (nil)
452 [ ] Foreground: white (sample)
453 [ ] Background: blue (sample)
454 [ ] Inverse: [Toggle] off (nil)
461 Each face attribute has its own line. The @samp{[@var{x}]} field
462 before the attribute name indicates whether the attribute is
463 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
464 attribute by invoking that field. When the attribute is enabled, you
465 can change the attribute value in the usual ways.
467 @c Is this true for XEmacs?
468 @c On a black-and-white display, the colors you can use for the
469 @c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
470 @c and @samp{gray3}. Emacs supports these shades of gray by using
471 @c background stipple patterns instead of a color.
473 Setting, saving and resetting a face work like the same operations for
474 options (@pxref{Changing an Option}).
476 A face can specify different appearances for different types of
477 display. For example, a face can make text red on a color display, but
478 use a bold font on a monochrome display. To specify multiple
479 appearances for a face, select @samp{Show Display Types} in the menu you
480 get from invoking @samp{[State]}.
482 @c It would be cool to implement this
483 @c @findex modify-face
484 @c Another more basic way to set the attributes of a specific face is
485 @c with @kbd{M-x modify-face}. This command reads the name of a face, then
486 @c reads the attributes one by one. For the color and stipple attributes,
487 @c the attribute's current value is the default---type just @key{RET} if
488 @c you don't want to change that attribute. Type @samp{none} if you want
489 @c to clear out the attribute.
491 @node Specific Customization
492 @subsubsection Customizing Specific Items
494 Instead of finding the options you want to change by moving down
495 through the structure of groups, you can specify the particular option,
496 face or group that you want to customize.
499 @item M-x customize-option @key{RET} @var{option} @key{RET}
500 Set up a customization buffer with just one option, @var{option}.
501 @item M-x customize-face @key{RET} @var{face} @key{RET}
502 Set up a customization buffer with just one face, @var{face}.
503 @item M-x customize-group @key{RET} @var{group} @key{RET}
504 Set up a customization buffer with just one group, @var{group}.
505 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
506 Set up a customization buffer with all the options, faces and groups
507 that match @var{regexp}.
508 @item M-x customize-saved
509 Set up a customization buffer containing all options and faces that you
510 have saved with customization buffers.
511 @item M-x customize-customized
512 Set up a customization buffer containing all options and faces that you
513 have customized but not saved.
516 @findex customize-option
517 If you want to alter a particular user option variable with the
518 customization buffer, and you know its name, you can use the command
519 @kbd{M-x customize-option} and specify the option name. This sets up
520 the customization buffer with just one option---the one that you asked
521 for. Editing, setting and saving the value work as described above, but
522 only for the specified option.
524 @findex customize-face
525 Likewise, you can modify a specific face, chosen by name, using
526 @kbd{M-x customize-face}.
528 @findex customize-group
529 You can also set up the customization buffer with a specific group,
530 using @kbd{M-x customize-group}. The immediate contents of the chosen
531 group, including option variables, faces, and other groups, all appear
532 as well. However, these subgroups' own contents start out hidden. You
533 can show their contents in the usual way, by invoking @samp{[Show]}.
535 @findex customize-apropos
536 To control more precisely what to customize, you can use @kbd{M-x
537 customize-apropos}. You specify a regular expression as argument; then
538 all options, faces and groups whose names match this regular expression
539 are set up in the customization buffer. If you specify an empty regular
540 expression, this includes @emph{all} groups, options and faces in the
541 customization buffer (but that takes a long time).
543 @findex customize-saved
544 @findex customize-customized
545 If you change option values and then decide the change was a mistake,
546 you can use two special commands to revisit your previous changes. Use
547 @kbd{customize-saved} to look at the options and faces that you have
548 saved. Use @kbd{M-x customize-customized} to look at the options and
549 faces that you have set but not saved.
552 @subsection Editing Variable Values
555 @item M-x list-options
556 Display a buffer listing names, values, and documentation of all options.
557 @item M-x edit-options
558 Change option values by editing a list of options.
562 @kbd{M-x list-options} displays a list of all Emacs option variables in
563 an Emacs buffer named @samp{*List Options*}. Each option is shown with its
564 documentation and its current value. Here is what a portion of it might
569 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
570 *List of directories to search programs to run in subprocesses.
571 Each element is a string (directory name)
572 or nil (try the default directory).
576 *Column beyond which automatic line-wrapping should happen.
577 Automatically becomes local when set in any fashion.
582 @kbd{M-x edit-options} goes one step further and immediately selects the
583 @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
584 which provides commands that allow you to point at an option and change its
589 Set the variable point is in or near to a new value read using the
592 Toggle the variable point is in or near: if the value was @code{nil},
593 it becomes @code{t}; otherwise it becomes @code{nil}.
595 Set the variable point is in or near to @code{t}.
597 Set the variable point is in or near to @code{nil}.
600 Move to the next or previous variable.
604 @subsection Local Variables
607 @item M-x make-local-variable
608 Make a variable have a local value in the current buffer.
609 @item M-x kill-local-variable
610 Make a variable use its global value in the current buffer.
611 @item M-x make-variable-buffer-local
612 Mark a variable so that setting it will make it local to the
613 buffer that is current at that time.
616 @cindex local variables
617 You can make any variable @dfn{local} to a specific Emacs buffer.
618 This means that the variable's value in that buffer is independent of
619 its value in other buffers. A few variables are always local in every
620 buffer. All other Emacs variables have a @dfn{global} value which is in
621 effect in all buffers that have not made the variable local.
623 Major modes always make the variables they set local to the buffer.
624 This is why changing major modes in one buffer has no effect on other
627 @findex make-local-variable
628 @kbd{M-x make-local-variable} reads the name of a variable and makes it
629 local to the current buffer. Further changes in this buffer will not
630 affect others, and changes in the global value will not affect this
633 @findex make-variable-buffer-local
634 @cindex per-buffer variables
635 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
636 changes the future behavior of the variable so that it automatically
637 becomes local when it is set. More precisely, once you have marked a
638 variable in this way, the usual ways of setting the
639 variable will automatically invoke @code{make-local-variable} first. We
640 call such variables @dfn{per-buffer} variables.
642 Some important variables have been marked per-buffer already. They
643 include @code{abbrev-mode}, @code{auto-fill-function},
644 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
645 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
646 @code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode},
647 @code{selective-display-ellipses}, @*@code{selective-display},
648 @code{tab-width}, and @code{truncate-lines}. Some other variables are
649 always local in every buffer, but they are used for internal
652 Note: the variable @code{auto-fill-function} was formerly named
653 @code{auto-fill-hook}.
655 @findex kill-local-variable
656 If you want a variable to cease to be local to the current buffer,
657 call @kbd{M-x kill-local-variable} and provide the name of a variable to
658 the prompt. The global value of the variable
659 is again in effect in this buffer. Setting the major mode kills all
660 the local variables of the buffer.
663 To set the global value of a variable, regardless of whether the
664 variable has a local value in the current buffer, you can use the
665 Lisp function @code{setq-default}. It works like @code{setq}.
666 If there is a local value in the current buffer, the local value is
667 not affected by @code{setq-default}; thus, the new global value may
668 not be visible until you switch to another buffer, as in the case of:
671 (setq-default fill-column 75)
675 @code{setq-default} is the only way to set the global value of a variable
676 that has been marked with @code{make-variable-buffer-local}.
678 @findex default-value
679 Programs can look at a variable's default value with @code{default-value}.
680 This function takes a symbol as an argument and returns its default value.
681 The argument is evaluated; usually you must quote it explicitly, as in
685 (default-value 'fill-column)
689 @subsection Local Variables in Files
690 @cindex local variables in files
692 A file can contain a @dfn{local variables list}, which specifies the
693 values to use for certain Emacs variables when that file is edited.
694 Visiting the file checks for a local variables list and makes each variable
695 in the list local to the buffer in which the file is visited, with the
696 value specified in the file.
698 A local variables list goes near the end of the file, in the last page.
699 (It is often best to put it on a page by itself.) The local variables list
700 starts with a line containing the string @samp{Local Variables:}, and ends
701 with a line containing the string @samp{End:}. In between come the
702 variable names and values, one set per line, as @samp{@var{variable}:@:
703 @var{value}}. The @var{value}s are not evaluated; they are used literally.
705 The line which starts the local variables list does not have to say
706 just @samp{Local Variables:}. If there is other text before @samp{Local
707 Variables:}, that text is called the @dfn{prefix}, and if there is other
708 text after, that is called the @dfn{suffix}. If a prefix or suffix are
709 present, each entry in the local variables list should have the prefix
710 before it and the suffix after it. This includes the @samp{End:} line.
711 The prefix and suffix are included to disguise the local variables list
712 as a comment so the compiler or text formatter will ignore it.
713 If you do not need to disguise the local variables list as a comment in
714 this way, there is no need to include a prefix or a suffix.@refill
716 Two ``variable'' names are special in a local variables list: a value
717 for the variable @code{mode} sets the major mode, and a value for the
718 variable @code{eval} is simply evaluated as an expression and the value
719 is ignored. These are not real variables; setting them in any other
720 context does not have the same effect. If @code{mode} is used in a
721 local variables list, it should be the first entry in the list.
723 Here is an example of a local variables list:
725 ;;; Local Variables: ***
727 ;;; comment-column:0 ***
728 ;;; comment-start: ";;; " ***
729 ;;; comment-end:"***" ***
733 Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.
734 Note also that comments in the file begin with and end with the same
735 strings. Presumably the file contains code in a language which is
736 enough like Lisp for Lisp mode to be useful but in which comments
737 start and end differently. The prefix and suffix are used in the local
738 variables list to make the list look like several lines of comments when
739 the compiler or interpreter for that language reads the file.
741 The start of the local variables list must be no more than 3000
742 characters from the end of the file, and must be in the last page if the
743 file is divided into pages. Otherwise, Emacs will not notice it is
744 there. The purpose is twofold: a stray @samp{Local Variables:}@: not in
745 the last page does not confuse Emacs, and Emacs never needs to search a
746 long file that contains no page markers and has no local variables list.
748 You may be tempted to turn on Auto Fill mode with a local variable
749 list. That is inappropriate. Whether you use Auto Fill mode or not is
750 a matter of personal taste, not a matter of the contents of particular
751 files. If you want to use Auto Fill, set up major mode hooks with your
752 init file to turn it on (when appropriate) for you alone
753 (@pxref{Init File}). Don't try to use a local variable list that would
754 impose your taste on everyone working with the file.
756 XEmacs allows you to specify local variables in the first line
757 of a file, in addition to specifying them in the @code{Local Variables}
758 section at the end of a file.
760 If the first line of a file contains two occurrences of @code{`-*-'},
761 XEmacs uses the information between them to determine what the major
762 mode and variable settings should be. For example, these are all legal:
765 ;;; -*- mode: emacs-lisp -*-
766 ;;; -*- mode: postscript; version-control: never -*-
767 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
770 For historical reasons, the syntax @code{`-*- modename -*-'} is allowed
771 as well; for example, you can use:
774 ;;; -*- emacs-lisp -*-
777 @vindex enable-local-variables
778 The variable @code{enable-local-variables} controls the use of local
779 variables lists in files you visit. The value can be @code{t},
780 @code{nil}, or something else. A value of @code{t} means local variables
781 lists are obeyed; @code{nil} means they are ignored; anything else means
784 The command @code{M-x normal-mode} always obeys local variables lists
785 and ignores this variable.
787 @node Keyboard Macros
788 @section Keyboard Macros
790 @cindex keyboard macros
791 A @dfn{keyboard macro} is a command defined by the user to abbreviate a
792 sequence of keys. For example, if you discover that you are about to type
793 @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
794 macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty.
799 Start defining a keyboard macro (@code{start-kbd-macro}).
801 End the definition of a keyboard macro (@code{end-kbd-macro}).
803 Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
805 Re-execute last keyboard macro, then add more keys to its definition.
807 When this point is reached during macro execution, ask for confirmation
808 (@code{kbd-macro-query}).
809 @item M-x name-last-kbd-macro
810 Give a command name (for the duration of the session) to the most
811 recently defined keyboard macro.
812 @item M-x insert-kbd-macro
813 Insert in the buffer a keyboard macro's definition, as Lisp code.
816 Keyboard macros differ from other Emacs commands in that they are
817 written in the Emacs command language rather than in Lisp. This makes it
818 easier for the novice to write them and makes them more convenient as
819 temporary hacks. However, the Emacs command language is not powerful
820 enough as a programming language to be useful for writing anything
821 general or complex. For such things, Lisp must be used.
823 You define a keyboard macro by executing the commands which are its
824 definition. Put differently, as you are defining a keyboard macro, the
825 definition is being executed for the first time. This way, you see
826 what the effects of your commands are, and don't have to figure
827 them out in your head. When you are finished, the keyboard macro is
828 defined and also has been executed once. You can then execute the same
829 set of commands again by invoking the macro.
832 * Basic Kbd Macro:: Defining and running keyboard macros.
833 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
834 * Kbd Macro Query:: Keyboard macros that do different things each use.
837 @node Basic Kbd Macro
838 @subsection Basic Use
843 @findex start-kbd-macro
844 @findex end-kbd-macro
845 @findex call-last-kbd-macro
846 To start defining a keyboard macro, type @kbd{C-x (}
847 (@code{start-kbd-macro}). From then on, anything you type continues to be
848 executed, but also becomes part of the definition of the macro. @samp{Def}
849 appears in the mode line to remind you of what is going on. When you are
850 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
851 definition, without becoming part of it.
860 defines a macro to move forward a word and then insert @samp{foo}.
862 You can give @kbd{C-x )} a repeat count as an argument, in which case it
863 repeats the macro that many times right after defining it, but defining
864 the macro counts as the first repetition (since it is executed as you
865 define it). If you give @kbd{C-x )} an argument of 4, it executes the
866 macro immediately 3 additional times. An argument of zero to @kbd{C-x
867 e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an
868 error or you type @kbd{C-g}).
870 Once you have defined a macro, you can invoke it again with the
871 @kbd{C-x e} command (@code{call-last-kbd-macro}). You can give the
872 command a repeat count numeric argument to execute the macro many times.
874 To repeat an operation at regularly spaced places in the
875 text, define a macro and include as part of the macro the commands to move
876 to the next place you want to use it. For example, if you want to change
877 each line, you should position point at the start of a line, and define a
878 macro to change that line and leave point at the start of the next line.
879 Repeating the macro will then operate on successive lines.
881 After you have terminated the definition of a keyboard macro, you can add
882 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
883 to plain @kbd{C-x (} followed by retyping the whole definition so far. As
884 a consequence it re-executes the macro as previously defined.
887 @subsection Naming and Saving Keyboard Macros
889 @findex name-last-kbd-macro
890 To save a keyboard macro for longer than until you define the
891 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
892 This reads a name as an argument using the minibuffer and defines that name
893 to execute the macro. The macro name is a Lisp symbol, and defining it in
894 this way makes it a valid command name for calling with @kbd{M-x} or for
895 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
896 specify a name that has a prior definition other than another keyboard
897 macro, Emacs prints an error message and nothing is changed.
899 @findex insert-kbd-macro
900 Once a macro has a command name, you can save its definition in a file.
901 You can then use it in another editing session. First visit the file
902 you want to save the definition in. Then use the command:
905 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
909 This inserts some Lisp code that, when executed later, will define the same
910 macro with the same definition it has now. You need not understand Lisp
911 code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
912 Then save the file. You can load the file with @code{load-file}
913 (@pxref{Lisp Libraries}). If the file you save in is your initialization file
914 (@pxref{Init File}), then the macro will be defined each
917 If you give @code{insert-kbd-macro} a prefix argument, it creates
918 additional Lisp code to record the keys (if any) that you have bound to the
919 keyboard macro, so that the macro is reassigned the same keys when you
922 @node Kbd Macro Query
923 @subsection Executing Macros With Variations
926 @findex kbd-macro-query
927 You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar
928 to that of @code{query-replace}. The macro asks you each time
929 whether to make a change. When you are defining the macro, type @kbd{C-x
930 q} at the point where you want the query to occur. During macro
931 definition, the @kbd{C-x q} does nothing, but when you invoke the macro,
932 @kbd{C-x q} reads a character from the terminal to decide whether to
935 The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL},
936 @kbd{C-d}, @kbd{C-l}, and @kbd{C-r}. Any other character terminates
937 execution of the keyboard macro and is then read as a command.
938 @key{SPC} means to continue. @key{DEL} means to skip the remainder of
939 this repetition of the macro, starting again from the beginning in the
940 next repetition. @kbd{C-d} means to skip the remainder of this
941 repetition and cancel further repetition. @kbd{C-l} redraws the frame
942 and asks you again for a character to specify what to do. @kbd{C-r} enters
943 a recursive editing level, in which you can perform editing that is not
944 part of the macro. When you exit the recursive edit using @kbd{C-M-c},
945 you are asked again how to continue with the keyboard macro. If you
946 type a @key{SPC} at this time, the rest of the macro definition is
947 executed. It is up to you to leave point and the text in a state such
948 that the rest of the macro will do what you want.@refill
950 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
951 different function. It enters a recursive edit reading input from the
952 keyboard, both when you type it during the definition of the macro and
953 when it is executed from the macro. During definition, the editing you do
954 inside the recursive edit does not become part of the macro. During macro
955 execution, the recursive edit gives you a chance to do some particularized
956 editing. @xref{Recursive Edit}.
959 @section Customizing Key Bindings
961 This section deals with the @dfn{keymaps} that define the bindings
962 between keys and functions, and shows how you can customize these bindings.
967 A command is a Lisp function whose definition provides for interactive
968 use. Like every Lisp function, a command has a function name, which is
969 a Lisp symbol whose name usually consists of lower case letters and
973 * Keymaps:: Definition of the keymap data structure.
974 Names of Emacs's standard keymaps.
975 * Rebinding:: How to redefine one key's meaning conveniently.
976 * Disabling:: Disabling a command means confirmation is required
977 before it can be executed. This is done to protect
978 beginners from surprises.
985 @cindex global keymap
987 The bindings between characters and command functions are recorded in
988 data structures called @dfn{keymaps}. Emacs has many of these. One, the
989 @dfn{global} keymap, defines the meanings of the single-character keys that
990 are defined regardless of major mode. It is the value of the variable
995 @vindex lisp-mode-map
996 Each major mode has another keymap, its @dfn{local keymap}, which
997 contains overriding definitions for the single-character keys that are
998 redefined in that mode. Each buffer records which local keymap is
999 installed for it at any time, and the current buffer's local keymap is
1000 the only one that directly affects command execution. The local keymaps
1001 for Lisp mode, C mode, and many other major modes always exist even when
1002 not in use. They are the values of the variables @code{lisp-mode-map},
1003 @code{c-mode-map}, and so on. For less frequently used major modes, the
1004 local keymap is sometimes constructed only when the mode is used for the
1005 first time in a session, to save space.
1008 @vindex minibuffer-local-map
1009 @vindex minibuffer-local-ns-map
1010 @vindex minibuffer-local-completion-map
1011 @vindex minibuffer-local-must-match-map
1012 @vindex repeat-complex-command-map
1013 @vindex isearch-mode-map
1014 There are local keymaps for the minibuffer, too; they contain various
1015 completion and exit commands.
1019 @code{minibuffer-local-map} is used for ordinary input (no completion).
1021 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1022 just like @key{RET}. This is used mainly for Mocklisp compatibility.
1024 @code{minibuffer-local-completion-map} is for permissive completion.
1026 @code{minibuffer-local-must-match-map} is for strict completion and
1027 for cautious completion.
1029 @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
1031 @code{isearch-mode-map} contains the bindings of the special keys which
1032 are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}.
1038 Finally, each prefix key has a keymap which defines the key sequences
1039 that start with it. For example, @code{ctl-x-map} is the keymap used for
1040 characters following a @kbd{C-x}.
1044 @code{ctl-x-map} is the variable name for the map used for characters that
1047 @code{help-map} is used for characters that follow @kbd{C-h}.
1049 @code{esc-map} is for characters that follow @key{ESC}. All Meta
1050 characters are actually defined by this map.
1052 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1054 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1057 The definition of a prefix key is the keymap to use for looking up
1058 the following character. Sometimes the definition is actually a Lisp
1059 symbol whose function definition is the following character keymap. The
1060 effect is the same, but it provides a command name for the prefix key that
1061 you can use as a description of what the prefix key is for. Thus the
1062 binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
1063 definition is the keymap for @kbd{C-x} commands, the value of
1064 @code{ctl-x-map}.@refill
1066 Prefix key definitions can appear in either the global
1067 map or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
1068 and @key{ESC} as prefix keys appear in the global map, so these prefix
1069 keys are always available. Major modes can locally redefine a key as a
1070 prefix by putting a prefix key definition for it in the local
1073 A mode can also put a prefix definition of a global prefix character such
1074 as @kbd{C-x} into its local map. This is how major modes override the
1075 definitions of certain keys that start with @kbd{C-x}. This case is
1076 special, because the local definition does not entirely replace the global
1077 one. When both the global and local definitions of a key are other
1078 keymaps, the next character is looked up in both keymaps, with the local
1079 definition overriding the global one. The character after the
1080 @kbd{C-x} is looked up in both the major mode's own keymap for redefined
1081 @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
1082 for @kbd{C-x} commands contains @code{nil}, the definition from the global
1083 keymap for @kbd{C-x} commands is used.@refill
1086 @subsection Changing Key Bindings
1087 @cindex key rebinding, this session
1088 @cindex rebinding keys, this session
1090 You can redefine an Emacs key by changing its entry in a keymap.
1091 You can change the global keymap, in which case the change is effective in
1092 all major modes except those that have their own overriding local
1093 definitions for the same key. Or you can change the current buffer's
1094 local map, which affects all buffers using the same major mode.
1097 * Interactive Rebinding:: Changing Key Bindings Interactively
1098 * Programmatic Rebinding:: Changing Key Bindings Programmatically
1099 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings
1102 @node Interactive Rebinding
1103 @subsubsection Changing Key Bindings Interactively
1104 @findex global-set-key
1105 @findex local-set-key
1106 @findex local-unset-key
1109 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1110 Defines @var{key} globally to run @var{cmd}.
1111 @item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET}
1112 Defines @var{key} locally (in the major mode now in effect) to run
1114 @item M-x local-unset-key @key{RET} @var{keys} @key{RET}
1115 Removes the local binding of @var{key}.
1118 @var{cmd} is a symbol naming an interactively-callable function.
1120 When called interactively, @var{key} is the next complete key sequence
1121 that you type. When called as a function, @var{key} is a string, a
1122 vector of events, or a vector of key-description lists as described in
1123 the @code{define-key} function description. The binding goes in
1124 the current buffer's local map, which is shared with other buffers in
1125 the same major mode.
1127 The following example:
1130 M-x global-set-key @key{RET} C-f next-line @key{RET}
1134 redefines @kbd{C-f} to move down a line. The fact that @var{cmd} is
1135 read second makes it serve as a kind of confirmation for @var{key}.
1137 These functions offer no way to specify a particular prefix keymap as
1138 the one to redefine in, but that is not necessary, as you can include
1139 prefixes in @var{key}. @var{key} is read by reading characters one by
1140 one until they amount to a complete key (that is, not a prefix key).
1141 Thus, if you type @kbd{C-f} for @var{key}, Emacs enters
1142 the minibuffer immediately to read @var{cmd}. But if you type
1143 @kbd{C-x}, another character is read; if that character is @kbd{4},
1144 another character is read, and so on. For example,@refill
1147 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1151 redefines @kbd{C-x 4 $} to run the (fictitious) command
1152 @code{spell-other-window}.
1155 @findex substitute-key-definition
1156 The most general way to modify a keymap is the function
1157 @code{define-key}, used in Lisp code (such as your init file).
1158 @code{define-key} takes three arguments: the keymap, the key to modify
1159 in it, and the new definition. @xref{Init File}, for an example.
1160 @code{substitute-key-definition} is used similarly; it takes three
1161 arguments, an old definition, a new definition, and a keymap, and
1162 redefines in that keymap all keys that were previously defined with the
1163 old definition to have the new definition instead.
1165 @node Programmatic Rebinding
1166 @subsubsection Changing Key Bindings Programmatically
1168 You can use the functions @code{global-set-key} and @code{define-key}
1169 to rebind keys under program control.
1172 @findex global-set-key
1175 @item @code{(global-set-key @var{keys} @var{cmd})}
1176 Defines @var{keys} globally to run @var{cmd}.
1177 @item @code{(define-key @var{keymap} @var{keys} @var{def})}
1178 Defines @var{keys} to run @var{def} in the keymap @var{keymap}.
1181 @var{keymap} is a keymap object.
1183 @var{keys} is the sequence of keystrokes to bind.
1185 @var{def} is anything that can be a key's definition:
1189 @code{nil}, meaning key is undefined in this keymap
1191 A command, that is, a Lisp function suitable for interactive calling
1193 A string or key sequence vector, which is treated as a keyboard macro
1195 A keymap to define a prefix key
1197 A symbol so that when the key is looked up, the symbol stands for its
1198 function definition, which should at that time be one of the above,
1199 or another symbol whose function definition is used, and so on
1201 A cons, @code{(string . defn)}, meaning that @var{defn} is the definition
1202 (@var{defn} should be a valid definition in its own right)
1204 A cons, @code{(keymap . char)}, meaning use the definition of
1205 @var{char} in map @var{keymap}
1208 For backward compatibility, XEmacs allows you to specify key
1209 sequences as strings. However, the preferred method is to use the
1210 representations of key sequences as vectors of keystrokes.
1211 @xref{Keystrokes}, for more information about the rules for constructing
1214 Emacs allows you to abbreviate representations for key sequences in
1215 most places where there is no ambiguity.
1216 Here are some rules for abbreviation:
1220 The keysym by itself is equivalent to a list of just that keysym, i.e.,
1221 @code{f1} is equivalent to @code{(f1)}.
1223 A keystroke by itself is equivalent to a vector containing just that
1224 keystroke, i.e., @code{(control a)} is equivalent to @code{[(control a)]}.
1226 You can use ASCII codes for keysyms that have them. i.e.,
1227 @code{65} is equivalent to @code{A}. (This is not so much an
1228 abbreviation as an alternate representation.)
1231 Here are some examples of programmatically binding keys:
1235 ;;; Bind @code{my-command} to @key{f1}
1236 (global-set-key 'f1 'my-command)
1238 ;;; Bind @code{my-command} to @kbd{Shift-f1}
1239 (global-set-key '(shift f1) 'my-command)
1241 ;;; Bind @code{my-command} to @kbd{C-c Shift-f1}
1242 (global-set-key '[(control c) (shift f1)] 'my-command)
1244 ;;; Bind @code{my-command} to the middle mouse button.
1245 (global-set-key 'button2 'my-command)
1247 ;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}}
1248 ;;; in the keymap that is in force when you are running @code{dired}.
1249 (define-key dired-mode-map '(meta control button3) 'my-command)
1253 @comment ;; note that these next four lines are not synonymous:
1255 @comment (global-set-key '(meta control delete) 'my-command)
1256 @comment (global-set-key '(meta control backspace) 'my-command)
1257 @comment (global-set-key '(meta control h) 'my-command)
1258 @comment (global-set-key '(meta control H) 'my-command)
1260 @comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''.
1262 @comment (global-set-key "\^J" 'my-command)
1264 @node Key Bindings Using Strings
1265 @subsubsection Using Strings for Changing Key Bindings
1267 For backward compatibility, you can still use strings to represent
1268 key sequences. Thus you can use commands like the following:
1271 ;;; Bind @code{end-of-line} to @kbd{C-f}
1272 (global-set-key "\C-f" 'end-of-line)
1275 Note, however, that in some cases you may be binding more than one
1276 key sequence by using a single command. This situation can
1277 arise because in ASCII, @kbd{C-i} and @key{TAB} have
1278 the same representation. Therefore, when Emacs sees:
1281 (global-set-key "\C-i" 'end-of-line)
1284 it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}.
1285 The solution XEmacs adopts is to bind both of these key
1288 @cindex redefining keys
1289 After binding a command to two key sequences with a form like:
1292 (define-key global-map "\^X\^I" 'command-1)
1295 it is possible to redefine only one of those sequences like so:
1298 (define-key global-map [(control x) (control i)] 'command-2)
1299 (define-key global-map [(control x) tab] 'command-3)
1302 This applies only when running under a window system. If you are
1303 talking to Emacs through an ASCII-only channel, you do not get any of
1306 Here is a table of pairs of key sequences that behave in a
1316 control @@ control space
1320 @subsection Disabling Commands
1321 @cindex disabled command
1323 Disabling a command marks it as requiring confirmation before it
1324 can be executed. The purpose of disabling a command is to prevent
1325 beginning users from executing it by accident and being confused.
1327 The direct mechanism for disabling a command is to have a non-@code{nil}
1328 @code{disabled} property on the Lisp symbol for the command. These
1329 properties are normally set by the user's init file with
1330 Lisp expressions such as:
1333 (put 'delete-region 'disabled t)
1338 If the value of the @code{disabled} property is a string, that string
1339 is included in the message printed when the command is used:
1342 (put 'delete-region 'disabled
1343 "Text deleted this way cannot be yanked back!\n")
1346 @findex disable-command
1347 @findex enable-command
1348 You can disable a command either by editing the init file
1349 directly or with the command @kbd{M-x disable-command}, which edits the
1350 init file for you. @xref{Init File}.
1352 When you attempt to invoke a disabled command interactively in Emacs,
1353 a window is displayed containing the command's name, its
1354 documentation, and some instructions on what to do next; then
1355 Emacs asks for input saying whether to execute the command as requested,
1356 enable it and execute, or cancel it. If you decide to enable the
1357 command, you are asked whether to do this permanently or just for the
1358 current session. Enabling permanently works by automatically editing
1359 your init file. You can use @kbd{M-x enable-command} at any
1360 time to enable any command permanently.
1362 Whether a command is disabled is independent of what key is used to
1363 invoke it; it also applies if the command is invoked using @kbd{M-x}.
1364 Disabling a command has no effect on calling it as a function from Lisp
1368 @section The Syntax Table
1369 @cindex syntax table
1371 All the Emacs commands which parse words or balance parentheses are
1372 controlled by the @dfn{syntax table}. The syntax table specifies which
1373 characters are opening delimiters, which are parts of words, which are
1374 string quotes, and so on. Actually, each major mode has its own syntax
1375 table (though sometimes related major modes use the same one) which it
1376 installs in each buffer that uses that major mode. The syntax table
1377 installed in the current buffer is the one that all commands use, so we
1378 call it ``the'' syntax table. A syntax table is a Lisp object, a vector of
1379 length 256 whose elements are numbers.
1382 * Entry: Syntax Entry. What the syntax table records for each character.
1383 * Change: Syntax Change. How to change the information.
1387 @subsection Information About Each Character
1389 The syntax table entry for a character is a number that encodes six
1390 pieces of information:
1394 The syntactic class of the character, represented as a small integer
1396 The matching delimiter, for delimiter characters only
1397 (the matching delimiter of @samp{(} is @samp{)}, and vice versa)
1399 A flag saying whether the character is the first character of a
1400 two-character comment starting sequence
1402 A flag saying whether the character is the second character of a
1403 two-character comment starting sequence
1405 A flag saying whether the character is the first character of a
1406 two-character comment ending sequence
1408 A flag saying whether the character is the second character of a
1409 two-character comment ending sequence
1412 The syntactic classes are stored internally as small integers, but are
1413 usually described to or by the user with characters. For example, @samp{(}
1414 is used to specify the syntactic class of opening delimiters. Here is a
1415 table of syntactic classes, with the characters that specify them.
1419 The class of whitespace characters.
1421 The class of word-constituent characters.
1423 The class of characters that are part of symbol names but not words.
1424 This class is represented by @samp{_} because the character @samp{_}
1425 has this class in both C and Lisp.
1427 The class of punctuation characters that do not fit into any other
1430 The class of opening delimiters.
1432 The class of closing delimiters.
1434 The class of expression-adhering characters. These characters are
1435 part of a symbol if found within or adjacent to one, and are part
1436 of a following expression if immediately preceding one, but are like
1437 whitespace if surrounded by whitespace.
1439 The class of string-quote characters. They match each other in pairs,
1440 and the characters within the pair all lose their syntactic
1441 significance except for the @samp{\} and @samp{/} classes of escape
1442 characters, which can be used to include a string-quote inside the
1445 The class of self-matching delimiters. This is intended for @TeX{}'s
1446 @samp{$}, which is used both to enter and leave math mode. Thus,
1447 a pair of matching @samp{$} characters surround each piece of math mode
1448 @TeX{} input. A pair of adjacent @samp{$} characters act like a single
1449 one for purposes of matching.
1452 The class of escape characters that always just deny the following
1453 character its special syntactic significance. The character after one
1454 of these escapes is always treated as alphabetic.
1456 The class of C-style escape characters. In practice, these are
1457 treated just like @samp{/}-class characters, because the extra
1458 possibilities for C escapes (such as being followed by digits) have no
1459 effect on where the containing expression ends.
1461 The class of comment-starting characters. Only single-character
1462 comment starters (such as @samp{;} in Lisp mode) are represented this
1465 The class of comment-ending characters. Newline has this syntax in
1469 @vindex parse-sexp-ignore-comments
1470 The characters flagged as part of two-character comment delimiters can
1471 have other syntactic functions most of the time. For example, @samp{/} and
1472 @samp{*} in C code, when found separately, have nothing to do with
1473 comments. The comment-delimiter significance overrides when the pair of
1474 characters occur together in the proper order. Only the list and sexp
1475 commands use the syntax table to find comments; the commands specifically
1476 for comments have other variables that tell them where to find comments.
1477 Moreover, the list and sexp commands notice comments only if
1478 @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
1479 to @code{nil} in modes where comment-terminator sequences are liable to
1480 appear where there is no comment, for example, in Lisp mode where the
1481 comment terminator is a newline but not every newline ends a comment.
1484 @subsection Altering Syntax Information
1486 It is possible to alter a character's syntax table entry by storing a new
1487 number in the appropriate element of the syntax table, but it would be hard
1488 to determine what number to use. Emacs therefore provides a command that
1489 allows you to specify the syntactic properties of a character in a
1492 @findex modify-syntax-entry
1493 @kbd{M-x modify-syntax-entry} is the command to change a character's
1494 syntax. It can be used interactively and is also used by major
1495 modes to initialize their own syntax tables. Its first argument is the
1496 character to change. The second argument is a string that specifies the
1497 new syntax. When called from Lisp code, there is a third, optional
1498 argument, which specifies the syntax table in which to make the change. If
1499 not supplied, or if this command is called interactively, the third
1500 argument defaults to the current buffer's syntax table.
1504 The first character in the string specifies the syntactic class. It
1505 is one of the characters in the previous table (@pxref{Syntax Entry}).
1508 The second character is the matching delimiter. For a character that
1509 is not an opening or closing delimiter, this should be a space, and may
1510 be omitted if no following characters are needed.
1513 The remaining characters are flags. The flag characters allowed are:
1517 Flag this character as the first of a two-character comment starting sequence.
1519 Flag this character as the second of a two-character comment starting sequence.
1521 Flag this character as the first of a two-character comment ending sequence.
1523 Flag this character as the second of a two-character comment ending sequence.
1528 @findex describe-syntax
1529 Use @kbd{C-h s} (@code{describe-syntax}) to display a description of
1530 the contents of the current syntax table. The description of each
1531 character includes both the string you have to pass to
1532 @code{modify-syntax-entry} to set up that character's current syntax,
1533 and some English to explain that string if necessary.
1536 @section The Init File
1538 @cindex Emacs initialization file
1539 @cindex key rebinding, permanent
1540 @cindex rebinding keys, permanently
1542 When you start Emacs, it normally loads either @file{.xemacs/init.el}
1543 or the file @file{.emacs} (whichever comes first) in your home directory.
1544 This file, if it exists, should contain Lisp code. It is called your
1545 initialization file or @dfn{init file}. Use the command line switch
1546 @samp{-q} to tell Emacs whether to load an init file (@pxref{Entering
1547 Emacs}). Use the command line switch @samp{-user-init-file}
1548 (@pxref{Command Switches}) to tell Emacs to load a different file
1549 instead of @file{~/.xemacs/init.el}/@file{~/.emacs}.
1551 When the init file is read, the variable @code{user-init-file} says
1552 which init file was loaded.
1554 At some sites there is a @dfn{default init file}, which is the
1555 library named @file{default.el}, found via the standard search path for
1556 libraries. The Emacs distribution contains no such library; your site
1557 may create one for local customizations. If this library exists, it is
1558 loaded whenever you start Emacs. But your init file, if any, is loaded
1559 first; if it sets @code{inhibit-default-init} non-@code{nil}, then
1560 @file{default} is not loaded.
1562 If you have a large amount of code in your init file, you should
1563 byte-compile it to @file{~/.xemacs/init.elc} or @file{~/.emacs.elc}.
1566 * Init Syntax:: Syntax of constants in Emacs Lisp.
1567 * Init Examples:: How to do some things with an init file.
1568 * Terminal Init:: Each terminal type can have an init file.
1572 @subsection Init File Syntax
1574 The init file contains one or more Lisp function call
1575 expressions. Each consists of a function name followed by
1576 arguments, all surrounded by parentheses. For example, @code{(setq
1577 fill-column 60)} represents a call to the function @code{setq} which is
1578 used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
1580 The second argument to @code{setq} is an expression for the new value
1581 of the variable. This can be a constant, a variable, or a function call
1582 expression. In the init file, constants are used most of the time.
1587 Integers are written in decimal, with an optional initial minus sign.
1589 If a sequence of digits is followed by a period and another sequence
1590 of digits, it is interpreted as a floating point number.
1592 The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to
1593 represent numbers in binary, octal, and hexadecimal notation (or radix).
1596 Lisp string syntax is the same as C string syntax with a few extra
1597 features. Use a double-quote character to begin and end a string constant.
1599 Newlines and special characters may be present literally in strings. They
1600 can also be represented as backslash sequences: @samp{\n} for newline,
1601 @samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab,
1602 @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
1603 backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
1604 character whose octal code is @var{ooo}. Backslash and double-quote are
1605 the only characters for which backslash sequences are mandatory.
1607 You can use @samp{\C-} as a prefix for a control character, as in
1608 @samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for
1609 a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
1610 Control-Meta-A.@refill
1613 Lisp character constant syntax consists of a @samp{?} followed by
1614 either a character or an escape sequence starting with @samp{\}.
1615 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
1616 strings and characters are not interchangeable in Lisp; some contexts
1617 require one and some contexts require the other.
1620 @code{t} stands for `true'.
1623 @code{nil} stands for `false'.
1625 @item Other Lisp objects
1626 Write a single-quote (') followed by the Lisp object you want.
1630 @subsection Init File Examples
1632 Here are some examples of doing certain commonly desired things with
1637 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
1641 (setq c-tab-always-indent nil)
1644 Here we have a variable whose value is normally @code{t} for `true'
1645 and the alternative is @code{nil} for `false'.
1648 Make searches case sensitive by default (in all buffers that do not
1652 (setq-default case-fold-search nil)
1655 This sets the default value, which is effective in all buffers that do
1656 not have local values for the variable. Setting @code{case-fold-search}
1657 with @code{setq} affects only the current buffer's local value, which
1658 is probably not what you want to do in an init file.
1661 Make Text mode the default mode for new buffers.
1664 (setq default-major-mode 'text-mode)
1667 Note that @code{text-mode} is used because it is the command for entering
1668 the mode we want. A single-quote is written before it to make a symbol
1669 constant; otherwise, @code{text-mode} would be treated as a variable name.
1672 Turn on Auto Fill mode automatically in Text mode and related modes.
1675 (setq text-mode-hook
1676 '(lambda () (auto-fill-mode 1)))
1679 Here we have a variable whose value should be a Lisp function. The
1680 function we supply is a list starting with @code{lambda}, and a single
1681 quote is written in front of it to make it (for the purpose of this
1682 @code{setq}) a list constant rather than an expression. Lisp functions
1683 are not explained here; for mode hooks it is enough to know that
1684 @code{(auto-fill-mode 1)} is an expression that will be executed when
1685 Text mode is entered. You could replace it with any other expression
1686 that you like, or with several expressions in a row.
1689 (setq text-mode-hook 'turn-on-auto-fill)
1692 This is another way to accomplish the same result.
1693 @code{turn-on-auto-fill} is a symbol whose function definition is
1694 @code{(lambda () (auto-fill-mode 1))}.
1697 Load the installed Lisp library named @file{foo} (actually a file
1698 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
1704 When the argument to @code{load} is a relative pathname, not starting
1705 with @samp{/} or @samp{~}, @code{load} searches the directories in
1706 @code{load-path} (@pxref{Loading}).
1709 Load the compiled Lisp file @file{foo.elc} from your home directory.
1715 Here an absolute file name is used, so no searching is done.
1718 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
1721 (global-set-key "\C-xl" 'make-symbolic-link)
1727 (define-key global-map "\C-xl" 'make-symbolic-link)
1730 Note once again the single-quote used to refer to the symbol
1731 @code{make-symbolic-link} instead of its value as a variable.
1734 Do the same thing for C mode only.
1737 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
1741 Bind the function key @key{F1} to a command in C mode.
1742 Note that the names of function keys must be lower case.
1745 (define-key c-mode-map 'f1 'make-symbolic-link)
1749 Bind the shifted version of @key{F1} to a command.
1752 (define-key c-mode-map '(shift f1) 'make-symbolic-link)
1756 Redefine all keys which now run @code{next-line} in Fundamental mode
1757 to run @code{forward-line} instead.
1760 (substitute-key-definition 'next-line 'forward-line
1765 Make @kbd{C-x C-v} undefined.
1768 (global-unset-key "\C-x\C-v")
1771 One reason to undefine a key is so that you can make it a prefix.
1772 Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
1773 a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
1777 Make @samp{$} have the syntax of punctuation in Text mode.
1778 Note the use of a character constant for @samp{$}.
1781 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
1785 Enable the use of the command @code{eval-expression} without confirmation.
1788 (put 'eval-expression 'disabled nil)
1793 @subsection Terminal-Specific Initialization
1795 Each terminal type can have a Lisp library to be loaded into Emacs when
1796 it is run on that type of terminal. For a terminal type named
1797 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
1798 found by searching the directories @code{load-path} as usual and trying the
1799 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
1800 subdirectory @file{term} of the directory where most Emacs libraries are
1803 The usual purpose of the terminal-specific library is to define the
1804 escape sequences used by the terminal's function keys using the library
1805 @file{keypad.el}. See the file
1806 @file{term/vt100.el} for an example of how this is done.@refill
1808 When the terminal type contains a hyphen, only the part of the name
1809 before the first hyphen is significant in choosing the library name.
1810 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
1811 the library @file{term/aaa}. The code in the library can use
1812 @code{(getenv "TERM")} to find the full terminal type name.@refill
1814 @vindex term-file-prefix
1815 The library's name is constructed by concatenating the value of the
1816 variable @code{term-file-prefix} and the terminal type. Your init
1817 file can prevent the loading of the terminal-specific library by setting
1818 @code{term-file-prefix} to @code{nil}. @xref{Init File}.
1820 @vindex term-setup-hook
1821 The value of the variable @code{term-setup-hook}, if not @code{nil}, is
1822 called as a function of no arguments at the end of Emacs initialization,
1823 after both your init file and any terminal-specific library have been
1824 read. @xref{Init File}. You can set the value in the init file to
1825 override part of any of the terminal-specific libraries and to define
1826 initializations for terminals that do not have a library.@refill
1829 @section Changing the Bell Sound
1830 @cindex audible bell, changing
1831 @cindex bell, changing
1833 @findex load-default-sounds
1836 You can now change how the audible bell sounds using the variable
1839 @code{sound-alist}'s value is an list associating symbols with, among
1840 other things, strings of audio-data. When @code{ding} is called with
1841 one of the symbols, the associated sound data is played instead of the
1842 standard beep. This only works if you are logged in on the console of a
1843 machine with audio hardware. To listen to a sound of the provided type,
1844 call the function @code{play-sound} with the argument @var{sound}. You
1845 can also set the volume of the sound with the optional argument
1846 @var{volume}.@refill
1849 Each element of @code{sound-alist} is a list describing a sound.
1850 The first element of the list is the name of the sound being defined.
1851 Subsequent elements of the list are alternating keyword/value pairs:
1855 A string of raw sound data, or the name of another sound to play.
1856 The symbol @code{t} here means use the default X beep.
1859 An integer from 0-100, defaulting to @code{bell-volume}.
1862 If using the default X beep, the pitch (Hz) to generate.
1865 If using the default X beep, the duration (milliseconds).
1868 For compatibility, elements of `sound-alist' may also be of the form:
1871 ( @var{sound-name} . @var{<sound>} )
1872 ( @var{sound-name} @var{<volume>} @var{<sound>} )
1875 You should probably add things to this list by calling the function
1876 @code{load-sound-file}.
1878 Note that you can only play audio data if running on the console screen
1879 of a machine with audio hardware which emacs understands, which at this
1880 time means a Sun SparcStation, SGI, or HP9000s700.
1882 Also note that the pitch, duration, and volume options are available
1883 everywhere, but most X servers ignore the `pitch' option.
1886 The variable @code{bell-volume} should be an integer from 0 to 100,
1887 with 100 being loudest, which controls how loud the sounds emacs makes
1888 should be. Elements of the @code{sound-alist} may override this value.
1889 This variable applies to the standard X bell sound as well as sound files.
1891 If the symbol @code{t} is in place of a sound-string, Emacs uses the
1892 default X beep. This allows you to define beep-types of
1893 different volumes even when not running on the console.
1895 @findex load-sound-file
1896 You can add things to this list by calling the function
1897 @code{load-sound-file}, which reads in an audio-file and adds its data to
1898 the sound-alist. You can specify the sound with the @var{sound-name}
1899 argument and the file into which the sounds are loaded with the
1900 @var{filename} argument. The optional @var{volume} argument sets the
1903 @code{load-sound-file (@var{filename sound-name} &optional @var{volume})}
1905 To load and install some sound files as beep-types, use the function
1906 @code{load-default-sounds} (note that this only works if you are on
1907 display 0 of a machine with audio hardware).
1909 The following beep-types are used by Emacs itself. Other Lisp
1910 packages may use other beep types, but these are the ones that the C
1911 kernel of Emacs uses.
1914 @item auto-save-error
1915 An auto-save does not succeed
1918 The Emacs command loop catches an error
1921 You type a key that is undefined
1923 @item undefined-click
1924 You use an undefined mouse-click combination
1927 Completion was not possible
1930 You type something other than the required @code{y} or @code{n}
1933 You type something other than @code{yes} or @code{no}
1936 @comment node-name, next, previous, up
1940 XEmacs has objects called extents and faces. An @dfn{extent}
1941 is a region of text and a @dfn{face} is a collection of textual
1942 attributes, such as fonts and colors. Every extent is displayed in some
1943 face; therefore, changing the properties of a face immediately updates the
1944 display of all associated extents. Faces can be frame-local: you can
1945 have a region of text that displays with completely different
1946 attributes when its buffer is viewed from a different X window.
1948 The display attributes of faces may be specified either in Lisp or through
1949 the X resource manager.
1951 @subsection Customizing Faces
1953 You can change the face of an extent with the functions in
1954 this section. All the functions prompt for a @var{face} as an
1955 argument; use completion for a list of possible values.
1958 @item M-x invert-face
1959 Swap the foreground and background colors of the given @var{face}.
1960 @item M-x make-face-bold
1961 Make the font of the given @var{face} bold. When called from a
1962 program, returns @code{nil} if this is not possible.
1963 @item M-x make-face-bold-italic
1964 Make the font of the given @var{face} bold italic.
1965 When called from a program, returns @code{nil} if not possible.
1966 @item M-x make-face-italic
1967 Make the font of the given @var{face} italic.
1968 When called from a program, returns @code{nil} if not possible.
1969 @item M-x make-face-unbold
1970 Make the font of the given @var{face} non-bold.
1971 When called from a program, returns @code{nil} if not possible.
1972 @item M-x make-face-unitalic
1973 Make the font of the given @var{face} non-italic.
1974 When called from a program, returns @code{nil} if not possible.
1975 @item M-x make-face-larger
1976 Make the font of the given @var{face} a little larger.
1977 When called from a program, returns @code{nil} if not possible.
1978 @item M-x make-face-smaller
1979 Make the font of the given @var{face} a little smaller.
1980 When called from a program, returns @code{nil} if not possible.
1981 @item M-x set-face-background
1982 Change the background color of the given @var{face}.
1983 @item M-x set-face-background-pixmap
1984 Change the background pixmap of the given @var{face}.
1985 @item M-x set-face-font
1986 Change the font of the given @var{face}.
1987 @item M-x set-face-foreground
1988 Change the foreground color of the given @var{face}.
1989 @item M-x set-face-underline-p
1990 Change whether the given @var{face} is underlined.
1993 @findex make-face-bold
1994 @findex make-face-bold-italic
1995 @findex make-face-italic
1996 @findex make-face-unbold
1997 @findex make-face-unitalic
1998 @findex make-face-larger
1999 @findex make-face-smaller
2002 You can exchange the foreground and background color of the selected
2003 @var{face} with the function @code{invert-face}. If the face does not
2004 specify both foreground and background, then its foreground and
2005 background are set to the background and foreground of the default face.
2006 When calling this from a program, you can supply the optional argument
2007 @var{frame} to specify which frame is affected; otherwise, all frames
2010 @findex set-face-background
2011 You can set the background color of the specified @var{face} with the
2012 function @code{set-face-background}. The argument @code{color} should
2013 be a string, the name of a color. When called from a program, if the
2014 optional @var{frame} argument is provided, the face is changed only
2015 in that frame; otherwise, it is changed in all frames.
2017 @findex set-face-background-pixmap
2018 You can set the background pixmap of the specified @var{face} with the
2019 function @code{set-face-background-pixmap}. The pixmap argument
2020 @var{name} should be a string, the name of a file of pixmap data. The
2021 directories listed in the @code{x-bitmap-file-path} variable are
2022 searched. The bitmap may also be a list of the form @code{(@var{width
2023 height data})}, where @var{width} and @var{height} are the size in
2024 pixels, and @var{data} is a string containing the raw bits of the
2025 bitmap. If the optional @var{frame} argument is provided, the face is
2026 changed only in that frame; otherwise, it is changed in all frames.
2028 The variable @code{x-bitmap-file-path} takes as a value a list of the
2029 directories in which X bitmap files may be found. If the value is
2030 @code{nil}, the list is initialized from the @code{*bitmapFilePath}
2033 If the environment variable @b{XBMLANGPATH} is set, then it is consulted
2034 before the @code{x-bitmap-file-path} variable.
2036 @findex set-face-font
2037 You can set the font of the specified @var{face} with the function
2038 @code{set-face-font}. The @var{font} argument should be a string, the
2039 name of a font. When called from a program, if the
2040 optional @var{frame} argument is provided, the face is changed only
2041 in that frame; otherwise, it is changed in all frames.
2043 @findex set-face-foreground
2044 You can set the foreground color of the specified @var{face} with the
2045 function @code{set-face-foreground}. The argument @var{color} should be
2046 a string, the name of a color. If the optional @var{frame} argument is
2047 provided, the face is changed only in that frame; otherwise, it is
2048 changed in all frames.
2050 @findex set-face-underline-p
2051 You can set underline the specified @var{face} with the function
2052 @code{set-face-underline-p}. The argument @var{underline-p} can be used
2053 to make underlining an attribute of the face or not. If the optional
2054 @var{frame} argument is provided, the face is changed only in that
2055 frame; otherwise, it is changed in all frames.
2057 @node Frame Components
2058 @section Frame Components
2060 You can control the presence and position of most frame components, such
2061 as the menubar, toolbars, and gutters.
2063 This section is not written yet. Try the Lisp Reference Manual:
2064 @ref{Menubar,,,lispref,}, @ref{Toolbar Intro,,,lispref,}, and
2065 @ref{Gutter Intro,,,lispref,}.
2068 @section X Resources
2070 @findex x-create-frame
2072 Historically, XEmacs has used the X resource application class @samp{Emacs}
2073 for its resources. Unfortunately, GNU Emacs uses the same application
2074 class, and resources are not compatible between the two Emacsen. This
2075 sharing of the application class often leads to trouble if you want to
2078 Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
2079 any XEmacs resources in the resource database when the X connection is
2080 initialized. Otherwise, it will use the class @samp{Emacs} for
2081 backwards compatibility. The variable @var{x-emacs-application-class}
2082 may be consulted to determine the application class being used.
2084 The examples in this section assume the application class is @samp{Emacs}.
2086 The Emacs resources are generally set per-frame. Each Emacs frame can have
2087 its own name or the same name as another, depending on the name passed to the
2088 @code{make-frame} function.
2090 You can specify resources for all frames with the syntax:
2093 Emacs*parameter: value
2100 Emacs*EmacsFrame.parameter:value
2104 You can specify resources for a particular frame with the syntax:
2107 Emacs*FRAME-NAME.parameter: value
2112 * Geometry Resources:: Controlling the size and position of frames.
2113 * Iconic Resources:: Controlling whether frames come up iconic.
2114 * Resource List:: List of resources settable on a frame or device.
2115 * Face Resources:: Controlling faces using resources.
2116 * Widgets:: The widget hierarchy for XEmacs.
2117 * Menubar Resources:: Specifying resources for the menubar.
2120 @node Geometry Resources
2121 @subsection Geometry Resources
2123 To make the default size of all Emacs frames be 80 columns by 55 lines,
2127 Emacs*EmacsFrame.geometry: 80x55
2131 To set the geometry of a particular frame named @samp{fred}, do this:
2134 Emacs*fred.geometry: 80x55
2138 Important! Do not use the following syntax:
2141 Emacs*geometry: 80x55
2145 You should never use @code{*geometry} with any X application. It does
2146 not say "make the geometry of Emacs be 80 columns by 55 lines." It
2147 really says, "make Emacs and all subwindows thereof be 80x55 in whatever
2148 units they care to measure in." In particular, that is both telling the
2149 Emacs text pane to be 80x55 in characters, and telling the menubar pane
2150 to be 80x55 pixels, which is surely not what you want.
2152 As a special case, this geometry specification also works (and sets the
2153 default size of all Emacs frames to 80 columns by 55 lines):
2156 Emacs.geometry: 80x55
2160 since that is the syntax used with most other applications (since most
2161 other applications have only one top-level window, unlike Emacs). In
2162 general, however, the top-level shell (the unmapped ApplicationShell
2163 widget named @samp{Emacs} that is the parent of the shell widgets that
2164 actually manage the individual frames) does not have any interesting
2165 resources on it, and you should set the resources on the frames instead.
2167 The @code{-geometry} command-line argument sets only the geometry of the
2168 initial frame created by Emacs.
2170 A more complete explanation of geometry-handling is
2174 The @code{-geometry} command-line option sets the @code{Emacs.geometry}
2175 resource, that is, the geometry of the ApplicationShell.
2178 For the first frame created, the size of the frame is taken from the
2179 ApplicationShell if it is specified, otherwise from the geometry of the
2183 For subsequent frames, the order is reversed: First the frame, and then
2184 the ApplicationShell.
2187 For the first frame created, the position of the frame is taken from the
2188 ApplicationShell (@code{Emacs.geometry}) if it is specified, otherwise
2189 from the geometry of the frame.
2192 For subsequent frames, the position is taken only from the frame, and
2193 never from the ApplicationShell.
2196 This is rather complicated, but it does seem to provide the most
2197 intuitive behavior with respect to the default sizes and positions of
2198 frames created in various ways.
2200 @node Iconic Resources
2201 @subsection Iconic Resources
2203 Analogous to @code{-geometry}, the @code{-iconic} command-line option
2204 sets the iconic flag of the ApplicationShell (@code{Emacs.iconic}) and
2205 always applies to the first frame created regardless of its name.
2206 However, it is possible to set the iconic flag on particular frames (by
2207 name) by using the @code{Emacs*FRAME-NAME.iconic} resource.
2210 @subsection Resource List
2212 Emacs frames accept the following resources:
2215 @item @code{geometry} (class @code{Geometry}): string
2216 Initial geometry for the frame. @xref{Geometry Resources}, for a
2217 complete discussion of how this works.
2219 @item @code{iconic} (class @code{Iconic}): boolean
2220 Whether this frame should appear in the iconified state.
2222 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int
2223 How many blank pixels to leave between the text and the edge of the
2226 @item @code{interline} (class @code{Interline}): int
2227 How many pixels to leave between each line (may not be implemented).
2229 @item @code{menubar} (class @code{Menubar}): boolean
2230 Whether newly-created frames should initially have a menubar. Set to
2233 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean
2234 Whether XEmacs should leave the initial frame unmapped when it starts
2235 up. This is useful if you are starting XEmacs as a server (e.g. in
2236 conjunction with gnuserv or the external client widget). You can also
2237 control this with the @code{-unmapped} command-line option.
2239 @item @code{barCursor} (class @code{BarColor}): boolean
2240 Whether the cursor should be displayed as a bar, or the traditional box.
2242 @item @code{cursorColor} (class @code{CursorColor}): color-name
2243 The color of the text cursor.
2245 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer
2246 How wide the vertical scrollbars should be, in pixels; 0 means no
2247 vertical scrollbars. You can also use a resource specification of the
2248 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources:
2249 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid),
2250 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you
2251 use the toolkit resources, though, because they're dependent on how
2252 exactly your particular build of XEmacs was configured.
2254 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer
2255 How high the horizontal scrollbars should be, in pixels; 0 means no
2256 horizontal scrollbars. You can also use a resource specification of the
2257 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources:
2258 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid),
2259 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you use
2260 the toolkit resources, though, because they're dependent on how exactly
2261 your particular build of XEmacs was configured.
2263 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string
2264 Where the horizontal and vertical scrollbars should be positioned. This
2265 should be one of the four strings @samp{BOTTOM_LEFT},
2266 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}. Default is
2267 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and
2268 @samp{BOTTOM_LEFT} for the Athena scrollbars.
2270 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer
2271 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer
2272 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer
2273 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer
2274 Height and width of the four possible toolbars.
2276 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name
2277 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name
2278 Color of the top and bottom shadows for the toolbars. NOTE: These resources
2279 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the
2280 toolbars at the top and bottom of the frame)! Rather, they affect the top
2281 and bottom shadows around the edges of all four kinds of toolbars.
2283 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name
2284 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name
2285 Pixmap of the top and bottom shadows for the toolbars. If set, these
2286 resources override the corresponding color resources. NOTE: These
2287 resources do @emph{not} have anything to do with the top and bottom
2288 toolbars (i.e. the toolbars at the top and bottom of the frame)!
2289 Rather, they affect the top and bottom shadows around the edges of all
2290 four kinds of toolbars.
2292 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer
2293 Thickness of the shadows around the toolbars, in pixels.
2295 @item @code{visualBell} (class @code{VisualBell}): boolean
2296 Whether XEmacs should flash the screen rather than making an audible beep.
2298 @item @code{bellVolume} (class @code{BellVolume}): integer
2299 Volume of the audible beep.
2301 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean
2302 Whether XEmacs should set the backing-store attribute of the X windows
2303 it creates. This increases the memory usage of the X server but decreases
2304 the amount of X traffic necessary to update the screen, and is useful
2305 when the connection to the X server goes over a low-bandwidth line
2306 such as a modem connection.
2309 Emacs devices accept the following resources:
2312 @item @code{textPointer} (class @code{Cursor}): cursor-name
2313 The cursor to use when the mouse is over text. This resource is used to
2314 initialize the variable @code{x-pointer-shape}.
2316 @item @code{selectionPointer} (class @code{Cursor}): cursor-name
2317 The cursor to use when the mouse is over a selectable text region (an
2318 extent with the @samp{highlight} property; for example, an Info
2319 cross-reference). This resource is used to initialize the variable
2320 @code{x-selection-pointer-shape}.
2322 @item @code{spacePointer} (class @code{Cursor}): cursor-name
2323 The cursor to use when the mouse is over a blank space in a buffer (that
2324 is, after the end of a line or after the end-of-file). This resource is
2325 used to initialize the variable @code{x-nontext-pointer-shape}.
2327 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name
2328 The cursor to use when the mouse is over a modeline. This resource is
2329 used to initialize the variable @code{x-mode-pointer-shape}.
2331 @item @code{gcPointer} (class @code{Cursor}): cursor-name
2332 The cursor to display when a garbage-collection is in progress. This
2333 resource is used to initialize the variable @code{x-gc-pointer-shape}.
2335 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name
2336 The cursor to use when the mouse is over the scrollbar. This resource
2337 is used to initialize the variable @code{x-scrollbar-pointer-shape}.
2339 @item @code{pointerColor} (class @code{Foreground}): color-name
2340 @itemx @code{pointerBackground} (class @code{Background}): color-name
2341 The foreground and background colors of the mouse cursor. These
2342 resources are used to initialize the variables
2343 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}.
2346 @node Face Resources
2347 @subsection Face Resources
2349 The attributes of faces are also per-frame. They can be specified as:
2352 Emacs.FACE_NAME.parameter: value
2359 Emacs*FRAME_NAME.FACE_NAME.parameter: value
2363 Faces accept the following resources:
2366 @item @code{attributeFont} (class @code{AttributeFont}): font-name
2367 The font of this face.
2369 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name
2370 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name
2371 The foreground and background colors of this face.
2373 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name
2374 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of Emacs
2375 supports @sc{xpm}), to use as a background stipple.
2377 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean
2378 Whether text in this face should be underlined.
2381 All text is displayed in some face, defaulting to the face named
2382 @code{default}. To set the font of normal text, use
2383 @code{Emacs*default.attributeFont}. To set it in the frame named
2384 @code{fred}, use @code{Emacs*fred.default.attributeFont}.
2386 These are the names of the predefined faces:
2390 Everything inherits from this.
2393 If this is not specified in the resource database, Emacs tries to find a
2394 bold version of the font of the default face.
2397 If this is not specified in the resource database, Emacs tries to find
2398 an italic version of the font of the default face.
2401 If this is not specified in the resource database, Emacs tries to find a
2402 bold-italic version of the font of the default face.
2405 This is the face that the modeline is displayed in. If not specified in
2406 the resource database, it is determined from the default face by
2407 reversing the foreground and background colors.
2410 This is the face that highlighted extents (for example, Info
2411 cross-references and possible completions, when the mouse passes over
2412 them) are displayed in.
2416 These are the faces that the left and right annotation margins are
2420 This is the face that mouse selections are displayed in.
2423 This is the face that the matched text being searched for is displayed
2427 This is the face of info menu items. If unspecified, it is copied from
2431 This is the face of info cross-references. If unspecified, it is copied
2432 from @code{bold}. (Note that, when the mouse passes over a
2433 cross-reference, the cross-reference's face is determined from a
2434 combination of the @code{info-xref} and @code{highlight} faces.)
2437 Other packages might define their own faces; to see a list of all faces,
2438 use any of the interactive face-manipulation commands such as
2439 @code{set-face-font} and type @samp{?} when you are prompted for the
2442 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not
2443 specified in the resource database, then XEmacs attempts to derive them
2444 from the font of the default face. It can only succeed at this if you
2445 have specified the default font using the XLFD (X Logical Font
2446 Description) format, which looks like
2449 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2453 If you use any of the other, less strict font name formats, some of which
2457 lucidasanstypewriter-12
2462 then XEmacs won't be able to guess the names of the bold and italic
2463 versions. All X fonts can be referred to via XLFD-style names, so you
2464 should use those forms. See the man pages for @samp{X(1)},
2465 @samp{xlsfonts(1)}, and @samp{xfontsel(1)}.
2470 There are several structural widgets between the terminal EmacsFrame
2471 widget and the top level ApplicationShell; the exact names and types of
2472 these widgets change from release to release (for example, they changed
2473 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
2474 subject to further change in the future, so you should avoid mentioning
2475 them in your resource database. The above-mentioned syntaxes should be
2476 forward- compatible. As of 19.13, the exact widget hierarchy is as
2480 INVOCATION-NAME "shell" "container" FRAME-NAME
2481 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
2484 where INVOCATION-NAME is the terminal component of the name of the
2485 XEmacs executable (usually @samp{xemacs}), and
2486 @samp{x-emacs-application-class} is generally @samp{Emacs}.
2488 @node Menubar Resources
2489 @subsection Menubar Resources
2491 As the menubar is implemented as a widget which is not a part of XEmacs
2492 proper, it does not use the face mechanism for specifying fonts and
2493 colors: It uses whatever resources are appropriate to the type of widget
2494 which is used to implement it.
2496 If Emacs was compiled to use only the Lucid Motif-lookalike menu widgets,
2497 then one way to specify the font of the menubar would be
2500 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2503 If both the Lucid Motif-lookalike menu widgets and X Font Sets are
2504 configured to allow multilingual menubars, then one uses
2507 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
2508 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
2511 That would specify fonts for a Japanese menubar. Specifying only one
2512 XLFD is acceptable; specifying more than one for a given registry
2513 (language) is also allowed. When X Font Sets are configured, some .font
2514 resources (eg, menubars) are ignored in favor of the corresponding
2517 If the Motif library is being used, then one would have to use
2520 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2523 because the Motif library uses the @code{fontList} resource name instead
2524 of @code{font}, which has subtly different semantics.
2526 The same is true of the scrollbars: They accept whichever resources are
2527 appropriate for the toolkit in use.