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 have
11 no effect on other Emacs jobs you may run at the same time or later. The
12 only way an Emacs job can affect anything outside of it is by writing a
13 file; in particular, the only way to make a customization `permanent' is to
14 put something in your @file{.emacs} file or other appropriate file to do the
15 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 @file{.emacs}
31 * Audible Bell:: Changing how Emacs sounds the bell.
32 * Faces:: Changing the fonts and colors of a region of text.
33 * X Resources:: X resources controlling various aspects of the
42 Minor modes are options which you can use or not. For example, Auto
43 Fill mode is a minor mode in which @key{SPC} breaks lines between words
44 as you type. All the minor modes are independent of each other and of
45 the selected major mode. Most minor modes inform you in the mode line
46 when they are on; for example, @samp{Fill} in the mode line means that
49 Append @code{-mode} to the name of a minor mode to get the name of a
50 command function that turns the mode on or off. Thus, the command to
51 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
52 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
53 if you wish. With no argument, the function turns the mode on if it was
54 off and off if it was on. This is known as @dfn{toggling}. A positive
55 argument always turns the mode on, and an explicit zero argument or a
56 negative argument always turns it off.
58 @cindex Auto Fill mode
59 @findex auto-fill-mode
60 Auto Fill mode allows you to enter filled text without breaking lines
61 explicitly. Emacs inserts newlines as necessary to prevent lines from
62 becoming too long. @xref{Filling}.
64 @cindex Overwrite mode
65 @findex overwrite-mode
66 Overwrite mode causes ordinary printing characters to replace existing
67 text instead of moving it to the right. For example, if point is in
68 front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite
69 mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill
73 Abbrev mode allows you to define abbreviations that automatically expand
74 as you type them. For example, @samp{amd} might expand to @samp{abbrev
75 mode}. @xref{Abbrevs}, for full information.
82 A @dfn{variable} is a Lisp symbol which has a value. Variable names
83 can contain any characters, but by convention they are words separated
84 by hyphens. A variable can also have a documentation string, which
85 describes what kind of value it should have and how the value will be
88 Lisp allows any variable to have any kind of value, but most variables
89 that Emacs uses require a value of a certain type. Often the value has
90 to be a string or a number. Sometimes we say that a certain feature is
91 turned on if a variable is ``non-@code{nil},'' meaning that if the
92 variable's value is @code{nil}, the feature is off, but the feature is
93 on for @i{any} other value. The conventional value to turn on the
94 feature---since you have to pick one particular value when you set the
95 variable---is @code{t}.
97 Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
98 program must, but the most interesting variables for you are the ones that
99 exist for the sake of customization. Emacs does not (usually) change the
100 values of these variables; instead, you set the values, and thereby alter
101 and control the behavior of certain Emacs commands. These variables are
102 called @dfn{options}. Most options are documented in this manual and
103 appear in the Variable Index (@pxref{Variable Index}).
105 One example of a variable which is an option is @code{fill-column}, which
106 specifies the position of the right margin (as a number of characters from
107 the left margin) to be used by the fill commands (@pxref{Filling}).
110 * Examining:: Examining or setting one variable's value.
111 * Easy Customization:: Convenient and easy customization of variables.
112 * Edit Options:: Examining or editing list of all variables' values.
113 * Locals:: Per-buffer values of variables.
114 * File Variables:: How files can specify variable values.
118 @subsection Examining and Setting Variables
119 @cindex setting variables
123 @itemx M-x describe-variable
124 Print the value and documentation of a variable.
126 @item M-x set-variable
127 Change the value of a variable.
131 @findex describe-variable
132 To examine the value of a single variable, use @kbd{C-h v}
133 (@code{describe-variable}), which reads a variable name using the
134 minibuffer, with completion. It prints both the value and the
135 documentation of the variable.
138 C-h v fill-column @key{RET}
142 prints something like:
145 fill-column's value is 75
148 *Column beyond which automatic line-wrapping should happen.
149 Automatically becomes local when set in any fashion.
154 The star at the beginning of the documentation indicates that this variable
155 is an option. @kbd{C-h v} is not restricted to options; it allows any
159 If you know which option you want to set, you can use @kbd{M-x
160 set-variable} to set it. This prompts for the variable name in the
161 minibuffer (with completion), and then prompts for a Lisp expression for the
162 new value using the minibuffer a second time. For example,
165 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
169 sets @code{fill-column} to 75, as if you had executed the Lisp expression
170 @code{(setq fill-column 75)}.
172 Setting variables in this way, like all means of customizing Emacs
173 except where explicitly stated, affects only the current Emacs session.
175 @node Easy Customization
176 @subsection Easy Customization Interface
179 @cindex customization buffer
180 A convenient way to find the user option variables that you want to
181 change, and then change them, is with @kbd{M-x customize}. This command
182 creates a @dfn{customization buffer} with which you can browse through
183 the Emacs user options in a logically organized structure, then edit and
184 set their values. You can also use the customization buffer to save
185 settings permanently. (Not all Emacs user options are included in this
186 structure as of yet, but we are adding the rest.)
189 * Groups: Customization Groups.
190 How options are classified in a structure.
191 * Changing an Option:: How to edit a value and set an option.
192 * Face Customization:: How to edit the attributes of a face.
193 * Specific Customization:: Making a customization buffer for specific
194 options, faces, or groups.
197 @node Customization Groups
198 @subsubsection Customization Groups
199 @cindex customization groups
201 For customization purposes, user options are organized into
202 @dfn{groups} to help you find them. Groups are collected into bigger
203 groups, all the way up to a master group called @code{Emacs}.
205 @kbd{M-x customize} creates a customization buffer that shows the
206 top-level @code{Emacs} group and the second-level groups immediately
207 under it. It looks like this, in part:
210 /- Emacs group: ---------------------------------------------------\
211 [State]: visible group members are all at standard settings.
212 Customization of the One True Editor.
216 Basic text editing facilities.
218 [Open] External group
219 Interfacing to external utilities.
221 @var{more second-level groups}
223 \- Emacs group end ------------------------------------------------/
228 This says that the buffer displays the contents of the @code{Emacs}
229 group. The other groups are listed because they are its contents. But
230 they are listed differently, without indentation and dashes, because
231 @emph{their} contents are not included. Each group has a single-line
232 documentation string; the @code{Emacs} group also has a @samp{[State]}
235 @cindex editable fields (customization buffer)
236 @cindex active fields (customization buffer)
237 Most of the text in the customization buffer is read-only, but it
238 typically includes some @dfn{editable fields} that you can edit. There
239 are also @dfn{active fields}; this means a field that does something
240 when you @dfn{invoke} it. To invoke an active field, either click on it
241 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
243 For example, the phrase @samp{[Open]} that appears in a second-level
244 group is an active field. Invoking the @samp{[Open]} field for a group
245 opens up a new customization buffer, which shows that group and its
246 contents. This field is a kind of hypertext link to another group.
248 The @code{Emacs} group does not include any user options itself, but
249 other groups do. By examining various groups, you will eventually find
250 the options and faces that belong to the feature you are interested in
251 customizing. Then you can use the customization buffer to set them.
253 @findex customize-browse
254 You can view the structure of customization groups on a larger scale
255 with @kbd{M-x customize-browse}. This command creates a special kind of
256 customization buffer which shows only the names of the groups (and
257 options and faces), and their structure.
259 In this buffer, you can show the contents of a group by invoking
260 @samp{[+]}. When the group contents are visible, this button changes to
261 @samp{[-]}; invoking that hides the group contents.
263 Each group, option or face name in this buffer has an active field
264 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
265 that active field creates an ordinary customization buffer showing just
266 that group and its contents, just that option, or just that face.
267 This is the way to set values in it.
269 @node Changing an Option
270 @subsubsection Changing an Option
272 Here is an example of what a user option looks like in the
273 customization buffer:
276 Kill Ring Max: [Hide] 30
277 [State]: this option is unchanged from its standard setting.
278 Maximum length of kill ring before oldest elements are thrown away.
281 The text following @samp{[Hide]}, @samp{30} in this case, indicates
282 the current value of the option. If you see @samp{[Show]} instead of
283 @samp{[Hide]}, it means that the value is hidden; the customization
284 buffer initially hides values that take up several lines. Invoke
285 @samp{[Show]} to show the value.
287 The line after the option name indicates the @dfn{customization state}
288 of the option: in the example above, it says you have not changed the
289 option yet. The word @samp{[State]} at the beginning of this line is
290 active; you can get a menu of various operations by invoking it with
291 @kbd{Mouse-1} or @key{RET}. These operations are essential for
292 customizing the variable.
294 The line after the @samp{[State]} line displays the beginning of the
295 option's documentation string. If there are more lines of
296 documentation, this line ends with @samp{[More]}; invoke this to show
297 the full documentation string.
299 To enter a new value for @samp{Kill Ring Max}, move point to the value
300 and edit it textually. For example, you can type @kbd{M-d}, then insert
303 When you begin to alter the text, you will see the @samp{[State]} line
304 change to say that you have edited the value:
307 [State]: you have edited the value as text, but not set the option.
310 @cindex setting option value
311 Editing the value does not actually set the option variable. To do
312 that, you must @dfn{set} the option. To do this, invoke the word
313 @samp{[State]} and choose @samp{Set for Current Session}.
315 The state of the option changes visibly when you set it:
318 [State]: you have set this option, but not saved it for future sessions.
321 You don't have to worry about specifying a value that is not valid;
322 setting the option checks for validity and will not really install an
325 @kindex M-TAB @r{(customization buffer)}
326 @findex widget-complete
327 While editing a value or field that is a file name, directory name,
328 command name, or anything else for which completion is defined, you can
329 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
331 Some options have a small fixed set of possible legitimate values.
332 These options don't let you edit the value textually. Instead, an
333 active field @samp{[Value Menu]} appears before the value; invoke this
334 field to edit the value. For a boolean ``on or off'' value, the active
335 field says @samp{[Toggle]}, and it changes to the other value.
336 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
337 take effect when you use the @samp{Set for Current Session} operation.
339 Some options have values with complex structure. For example, the
340 value of @code{load-path} is a list of directories. Here is how it
341 appears in the customization buffer:
345 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
346 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
347 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
348 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
349 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
350 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
352 [State]: this item has been changed outside the customization buffer.
353 List of directories to search for files to load....
357 Each directory in the list appears on a separate line, and each line has
358 several editable or active fields.
360 You can edit any of the directory names. To delete a directory from
361 the list, invoke @samp{[DEL]} on that line. To insert a new directory in
362 the list, invoke @samp{[INS]} at the point where you want to insert it.
364 You can also invoke @samp{[Current dir?]} to switch between including
365 a specific named directory in the path, and including @code{nil} in the
366 path. (@code{nil} in a search path means ``try the current
369 @kindex TAB @r{(customization buffer)}
370 @kindex S-TAB @r{(customization buffer)}
371 @findex widget-forward
372 @findex widget-backward
373 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
374 moving through the customization buffer. @key{TAB}
375 (@code{widget-forward}) moves forward to the next active or editable
376 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
377 previous active or editable field.
379 Typing @key{RET} on an editable field also moves forward, just like
380 @key{TAB}. The reason for this is that people have a tendency to type
381 @key{RET} when they are finished editing a field. If you have occasion
382 to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
385 @cindex saving option value
386 Setting the option changes its value in the current Emacs session;
387 @dfn{saving} the value changes it for future sessions as well. This
388 works by writing code into your @file{~/.emacs} file so as to set the
389 option variable again each time you start Emacs. To save the option,
390 invoke @samp{[State]} and select the @samp{Save for Future Sessions}
393 You can also restore the option to its standard value by invoking
394 @samp{[State]} and selecting the @samp{Reset} operation. There are
395 actually three reset operations:
398 @item Reset to Current
399 If you have made some modifications and not yet set the option,
400 this restores the text in the customization buffer to match
404 This restores the value of the option to the last saved value,
405 and updates the text accordingly.
407 @item Reset to Standard Settings
408 This sets the option to its standard value, and updates the text
409 accordingly. This also eliminates any saved value for the option,
410 so that you will get the standard value in future Emacs sessions.
413 The state of a group indicates whether anything in that group has been
414 edited, set or saved. You can select @samp{Set for Current Session},
415 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
416 operation for the group; these operations on the group apply to all
417 options in the group and its subgroups.
419 Near the top of the customization buffer there are two lines
420 containing several active fields:
423 [Set] [Save] [Reset] [Done]
427 Invoking @samp{[Done]} buries this customization buffer. Each of the
428 other fields performs an operation---set, save or reset---on each of the
429 items in the buffer that could meaningfully be set, saved or reset.
431 @node Face Customization
432 @subsubsection Customizing Faces
433 @cindex customizing faces
436 @cindex fonts and faces
438 In addition to user options, some customization groups also include
439 faces. When you show the contents of a group, both the user options and
440 the faces in the group appear in the customization buffer. Here is an
441 example of how a face looks:
444 Custom Changed Face: (sample)
445 [State]: this face is unchanged from its standard setting.
446 Face used when the customize item has been changed.
447 Parent groups: [Custom Magic Faces]
448 Attributes: [ ] Bold: [Toggle] off (nil)
449 [ ] Italic: [Toggle] off (nil)
450 [ ] Underline: [Toggle] off (nil)
451 [ ] Foreground: white (sample)
452 [ ] Background: blue (sample)
453 [ ] Inverse: [Toggle] off (nil)
460 Each face attribute has its own line. The @samp{[@var{x}]} field
461 before the attribute name indicates whether the attribute is
462 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
463 attribute by invoking that field. When the attribute is enabled, you
464 can change the attribute value in the usual ways.
466 @c Is this true for XEmacs?
467 @c On a black-and-white display, the colors you can use for the
468 @c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
469 @c and @samp{gray3}. Emacs supports these shades of gray by using
470 @c background stipple patterns instead of a color.
472 Setting, saving and resetting a face work like the same operations for
473 options (@pxref{Changing an Option}).
475 A face can specify different appearances for different types of
476 display. For example, a face can make text red on a color display, but
477 use a bold font on a monochrome display. To specify multiple
478 appearances for a face, select @samp{Show Display Types} in the menu you
479 get from invoking @samp{[State]}.
481 @c It would be cool to implement this
482 @c @findex modify-face
483 @c Another more basic way to set the attributes of a specific face is
484 @c with @kbd{M-x modify-face}. This command reads the name of a face, then
485 @c reads the attributes one by one. For the color and stipple attributes,
486 @c the attribute's current value is the default---type just @key{RET} if
487 @c you don't want to change that attribute. Type @samp{none} if you want
488 @c to clear out the attribute.
490 @node Specific Customization
491 @subsubsection Customizing Specific Items
493 Instead of finding the options you want to change by moving down
494 through the structure of groups, you can specify the particular option,
495 face or group that you want to customize.
498 @item M-x customize-option @key{RET} @var{option} @key{RET}
499 Set up a customization buffer with just one option, @var{option}.
500 @item M-x customize-face @key{RET} @var{face} @key{RET}
501 Set up a customization buffer with just one face, @var{face}.
502 @item M-x customize-group @key{RET} @var{group} @key{RET}
503 Set up a customization buffer with just one group, @var{group}.
504 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
505 Set up a customization buffer with all the options, faces and groups
506 that match @var{regexp}.
507 @item M-x customize-saved
508 Set up a customization buffer containing all options and faces that you
509 have saved with customization buffers.
510 @item M-x customize-customized
511 Set up a customization buffer containing all options and faces that you
512 have customized but not saved.
515 @findex customize-option
516 If you want to alter a particular user option variable with the
517 customization buffer, and you know its name, you can use the command
518 @kbd{M-x customize-option} and specify the option name. This sets up
519 the customization buffer with just one option---the one that you asked
520 for. Editing, setting and saving the value work as described above, but
521 only for the specified option.
523 @findex customize-face
524 Likewise, you can modify a specific face, chosen by name, using
525 @kbd{M-x customize-face}.
527 @findex customize-group
528 You can also set up the customization buffer with a specific group,
529 using @kbd{M-x customize-group}. The immediate contents of the chosen
530 group, including option variables, faces, and other groups, all appear
531 as well. However, these subgroups' own contents start out hidden. You
532 can show their contents in the usual way, by invoking @samp{[Show]}.
534 @findex customize-apropos
535 To control more precisely what to customize, you can use @kbd{M-x
536 customize-apropos}. You specify a regular expression as argument; then
537 all options, faces and groups whose names match this regular expression
538 are set up in the customization buffer. If you specify an empty regular
539 expression, this includes @emph{all} groups, options and faces in the
540 customization buffer (but that takes a long time).
542 @findex customize-saved
543 @findex customize-customized
544 If you change option values and then decide the change was a mistake,
545 you can use two special commands to revisit your previous changes. Use
546 @kbd{customize-saved} to look at the options and faces that you have
547 saved. Use @kbd{M-x customize-customized} to look at the options and
548 faces that you have set but not saved.
551 @subsection Editing Variable Values
554 @item M-x list-options
555 Display a buffer listing names, values, and documentation of all options.
556 @item M-x edit-options
557 Change option values by editing a list of options.
561 @kbd{M-x list-options} displays a list of all Emacs option variables in
562 an Emacs buffer named @samp{*List Options*}. Each option is shown with its
563 documentation and its current value. Here is what a portion of it might
568 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
569 *List of directories to search programs to run in subprocesses.
570 Each element is a string (directory name)
571 or nil (try the default directory).
575 *Column beyond which automatic line-wrapping should happen.
576 Automatically becomes local when set in any fashion.
581 @kbd{M-x edit-options} goes one step further and immediately selects the
582 @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
583 which provides commands that allow you to point at an option and change its
588 Set the variable point is in or near to a new value read using the
591 Toggle the variable point is in or near: if the value was @code{nil},
592 it becomes @code{t}; otherwise it becomes @code{nil}.
594 Set the variable point is in or near to @code{t}.
596 Set the variable point is in or near to @code{nil}.
599 Move to the next or previous variable.
603 @subsection Local Variables
606 @item M-x make-local-variable
607 Make a variable have a local value in the current buffer.
608 @item M-x kill-local-variable
609 Make a variable use its global value in the current buffer.
610 @item M-x make-variable-buffer-local
611 Mark a variable so that setting it will make it local to the
612 buffer that is current at that time.
615 @cindex local variables
616 You can make any variable @dfn{local} to a specific Emacs buffer.
617 This means that the variable's value in that buffer is independent of
618 its value in other buffers. A few variables are always local in every
619 buffer. All other Emacs variables have a @dfn{global} value which is in
620 effect in all buffers that have not made the variable local.
622 Major modes always make the variables they set local to the buffer.
623 This is why changing major modes in one buffer has no effect on other
626 @findex make-local-variable
627 @kbd{M-x make-local-variable} reads the name of a variable and makes it
628 local to the current buffer. Further changes in this buffer will not
629 affect others, and changes in the global value will not affect this
632 @findex make-variable-buffer-local
633 @cindex per-buffer variables
634 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
635 changes the future behavior of the variable so that it automatically
636 becomes local when it is set. More precisely, once you have marked a
637 variable in this way, the usual ways of setting the
638 variable will automatically invoke @code{make-local-variable} first. We
639 call such variables @dfn{per-buffer} variables.
641 Some important variables have been marked per-buffer already. They
642 include @code{abbrev-mode}, @code{auto-fill-function},
643 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
644 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
645 @code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode},
646 @code{selective-display-ellipses}, @*@code{selective-display},
647 @code{tab-width}, and @code{truncate-lines}. Some other variables are
648 always local in every buffer, but they are used for internal
651 Note: the variable @code{auto-fill-function} was formerly named
652 @code{auto-fill-hook}.
654 @findex kill-local-variable
655 If you want a variable to cease to be local to the current buffer,
656 call @kbd{M-x kill-local-variable} and provide the name of a variable to
657 the prompt. The global value of the variable
658 is again in effect in this buffer. Setting the major mode kills all
659 the local variables of the buffer.
662 To set the global value of a variable, regardless of whether the
663 variable has a local value in the current buffer, you can use the
664 Lisp function @code{setq-default}. It works like @code{setq}.
665 If there is a local value in the current buffer, the local value is
666 not affected by @code{setq-default}; thus, the new global value may
667 not be visible until you switch to another buffer, as in the case of:
670 (setq-default fill-column 75)
674 @code{setq-default} is the only way to set the global value of a variable
675 that has been marked with @code{make-variable-buffer-local}.
677 @findex default-value
678 Programs can look at a variable's default value with @code{default-value}.
679 This function takes a symbol as an argument and returns its default value.
680 The argument is evaluated; usually you must quote it explicitly, as in
684 (default-value 'fill-column)
688 @subsection Local Variables in Files
689 @cindex local variables in files
691 A file can contain a @dfn{local variables list}, which specifies the
692 values to use for certain Emacs variables when that file is edited.
693 Visiting the file checks for a local variables list and makes each variable
694 in the list local to the buffer in which the file is visited, with the
695 value specified in the file.
697 A local variables list goes near the end of the file, in the last page.
698 (It is often best to put it on a page by itself.) The local variables list
699 starts with a line containing the string @samp{Local Variables:}, and ends
700 with a line containing the string @samp{End:}. In between come the
701 variable names and values, one set per line, as @samp{@var{variable}:@:
702 @var{value}}. The @var{value}s are not evaluated; they are used literally.
704 The line which starts the local variables list does not have to say
705 just @samp{Local Variables:}. If there is other text before @samp{Local
706 Variables:}, that text is called the @dfn{prefix}, and if there is other
707 text after, that is called the @dfn{suffix}. If a prefix or suffix are
708 present, each entry in the local variables list should have the prefix
709 before it and the suffix after it. This includes the @samp{End:} line.
710 The prefix and suffix are included to disguise the local variables list
711 as a comment so the compiler or text formatter will ignore it.
712 If you do not need to disguise the local variables list as a comment in
713 this way, there is no need to include a prefix or a suffix.@refill
715 Two ``variable'' names are special in a local variables list: a value
716 for the variable @code{mode} sets the major mode, and a value for the
717 variable @code{eval} is simply evaluated as an expression and the value
718 is ignored. These are not real variables; setting them in any other
719 context does not have the same effect. If @code{mode} is used in a
720 local variables list, it should be the first entry in the list.
722 Here is an example of a local variables list:
724 ;;; Local Variables: ***
726 ;;; comment-column:0 ***
727 ;;; comment-start: ";;; " ***
728 ;;; comment-end:"***" ***
732 Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.
733 Note also that comments in the file begin with and end with the same
734 strings. Presumably the file contains code in a language which is
735 enough like Lisp for Lisp mode to be useful but in which comments
736 start and end differently. The prefix and suffix are used in the local
737 variables list to make the list look like several lines of comments when
738 the compiler or interpreter for that language reads the file.
740 The start of the local variables list must be no more than 3000
741 characters from the end of the file, and must be in the last page if the
742 file is divided into pages. Otherwise, Emacs will not notice it is
743 there. The purpose is twofold: a stray @samp{Local Variables:}@: not in
744 the last page does not confuse Emacs, and Emacs never needs to search a
745 long file that contains no page markers and has no local variables list.
747 You may be tempted to turn on Auto Fill mode with a local variable
748 list. That is inappropriate. Whether you use Auto Fill mode or not is
749 a matter of personal taste, not a matter of the contents of particular
750 files. If you want to use Auto Fill, set up major mode hooks with your
751 @file{.emacs} file to turn it on (when appropriate) for you alone
752 (@pxref{Init File}). Don't try to use a local variable list that would
753 impose your taste on everyone working with the file.
755 XEmacs allows you to specify local variables in the first line
756 of a file, in addition to specifying them in the @code{Local Variables}
757 section at the end of a file.
759 If the first line of a file contains two occurrences of @code{`-*-'},
760 XEmacs uses the information between them to determine what the major
761 mode and variable settings should be. For example, these are all legal:
764 ;;; -*- mode: emacs-lisp -*-
765 ;;; -*- mode: postscript; version-control: never -*-
766 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
769 For historical reasons, the syntax @code{`-*- modename -*-'} is allowed
770 as well; for example, you can use:
773 ;;; -*- emacs-lisp -*-
776 @vindex enable-local-variables
777 The variable @code{enable-local-variables} controls the use of local
778 variables lists in files you visit. The value can be @code{t},
779 @code{nil}, or something else. A value of @code{t} means local variables
780 lists are obeyed; @code{nil} means they are ignored; anything else means
783 The command @code{M-x normal-mode} always obeys local variables lists
784 and ignores this variable.
786 @node Keyboard Macros
787 @section Keyboard Macros
789 @cindex keyboard macros
790 A @dfn{keyboard macro} is a command defined by the user to abbreviate a
791 sequence of keys. For example, if you discover that you are about to type
792 @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
793 macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty.
798 Start defining a keyboard macro (@code{start-kbd-macro}).
800 End the definition of a keyboard macro (@code{end-kbd-macro}).
802 Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
804 Re-execute last keyboard macro, then add more keys to its definition.
806 When this point is reached during macro execution, ask for confirmation
807 (@code{kbd-macro-query}).
808 @item M-x name-last-kbd-macro
809 Give a command name (for the duration of the session) to the most
810 recently defined keyboard macro.
811 @item M-x insert-kbd-macro
812 Insert in the buffer a keyboard macro's definition, as Lisp code.
815 Keyboard macros differ from other Emacs commands in that they are
816 written in the Emacs command language rather than in Lisp. This makes it
817 easier for the novice to write them and makes them more convenient as
818 temporary hacks. However, the Emacs command language is not powerful
819 enough as a programming language to be useful for writing anything
820 general or complex. For such things, Lisp must be used.
822 You define a keyboard macro by executing the commands which are its
823 definition. Put differently, as you are defining a keyboard macro, the
824 definition is being executed for the first time. This way, you see
825 what the effects of your commands are, and don't have to figure
826 them out in your head. When you are finished, the keyboard macro is
827 defined and also has been executed once. You can then execute the same
828 set of commands again by invoking the macro.
831 * Basic Kbd Macro:: Defining and running keyboard macros.
832 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
833 * Kbd Macro Query:: Keyboard macros that do different things each use.
836 @node Basic Kbd Macro
837 @subsection Basic Use
842 @findex start-kbd-macro
843 @findex end-kbd-macro
844 @findex call-last-kbd-macro
845 To start defining a keyboard macro, type @kbd{C-x (}
846 (@code{start-kbd-macro}). From then on, anything you type continues to be
847 executed, but also becomes part of the definition of the macro. @samp{Def}
848 appears in the mode line to remind you of what is going on. When you are
849 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
850 definition, without becoming part of it.
859 defines a macro to move forward a word and then insert @samp{foo}.
861 You can give @kbd{C-x )} a repeat count as an argument, in which case it
862 repeats the macro that many times right after defining it, but defining
863 the macro counts as the first repetition (since it is executed as you
864 define it). If you give @kbd{C-x )} an argument of 4, it executes the
865 macro immediately 3 additional times. An argument of zero to @kbd{C-x
866 e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an
867 error or you type @kbd{C-g}).
869 Once you have defined a macro, you can invoke it again with the
870 @kbd{C-x e} command (@code{call-last-kbd-macro}). You can give the
871 command a repeat count numeric argument to execute the macro many times.
873 To repeat an operation at regularly spaced places in the
874 text, define a macro and include as part of the macro the commands to move
875 to the next place you want to use it. For example, if you want to change
876 each line, you should position point at the start of a line, and define a
877 macro to change that line and leave point at the start of the next line.
878 Repeating the macro will then operate on successive lines.
880 After you have terminated the definition of a keyboard macro, you can add
881 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
882 to plain @kbd{C-x (} followed by retyping the whole definition so far. As
883 a consequence it re-executes the macro as previously defined.
886 @subsection Naming and Saving Keyboard Macros
888 @findex name-last-kbd-macro
889 To save a keyboard macro for longer than until you define the
890 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
891 This reads a name as an argument using the minibuffer and defines that name
892 to execute the macro. The macro name is a Lisp symbol, and defining it in
893 this way makes it a valid command name for calling with @kbd{M-x} or for
894 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
895 specify a name that has a prior definition other than another keyboard
896 macro, Emacs prints an error message and nothing is changed.
898 @findex insert-kbd-macro
899 Once a macro has a command name, you can save its definition in a file.
900 You can then use it in another editing session. First visit the file
901 you want to save the definition in. Then use the command:
904 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
908 This inserts some Lisp code that, when executed later, will define the same
909 macro with the same definition it has now. You need not understand Lisp
910 code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
911 Then save the file. You can load the file with @code{load-file}
912 (@pxref{Lisp Libraries}). If the file you save in is your initialization file
913 @file{~/.emacs} (@pxref{Init File}), then the macro will be defined each
916 If you give @code{insert-kbd-macro} a prefix argument, it creates
917 additional Lisp code to record the keys (if any) that you have bound to the
918 keyboard macro, so that the macro is reassigned the same keys when you
921 @node Kbd Macro Query
922 @subsection Executing Macros With Variations
925 @findex kbd-macro-query
926 You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar
927 to that of @code{query-replace}. The macro asks you each time
928 whether to make a change. When you are defining the macro, type @kbd{C-x
929 q} at the point where you want the query to occur. During macro
930 definition, the @kbd{C-x q} does nothing, but when you invoke the macro,
931 @kbd{C-x q} reads a character from the terminal to decide whether to
934 The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL},
935 @kbd{C-d}, @kbd{C-l}, and @kbd{C-r}. Any other character terminates
936 execution of the keyboard macro and is then read as a command.
937 @key{SPC} means to continue. @key{DEL} means to skip the remainder of
938 this repetition of the macro, starting again from the beginning in the
939 next repetition. @kbd{C-d} means to skip the remainder of this
940 repetition and cancel further repetition. @kbd{C-l} redraws the frame
941 and asks you again for a character to specify what to do. @kbd{C-r} enters
942 a recursive editing level, in which you can perform editing that is not
943 part of the macro. When you exit the recursive edit using @kbd{C-M-c},
944 you are asked again how to continue with the keyboard macro. If you
945 type a @key{SPC} at this time, the rest of the macro definition is
946 executed. It is up to you to leave point and the text in a state such
947 that the rest of the macro will do what you want.@refill
949 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
950 different function. It enters a recursive edit reading input from the
951 keyboard, both when you type it during the definition of the macro and
952 when it is executed from the macro. During definition, the editing you do
953 inside the recursive edit does not become part of the macro. During macro
954 execution, the recursive edit gives you a chance to do some particularized
955 editing. @xref{Recursive Edit}.
958 @section Customizing Key Bindings
960 This section deals with the @dfn{keymaps} that define the bindings
961 between keys and functions, and shows how you can customize these bindings.
966 A command is a Lisp function whose definition provides for interactive
967 use. Like every Lisp function, a command has a function name, which is
968 a Lisp symbol whose name usually consists of lower case letters and
972 * Keymaps:: Definition of the keymap data structure.
973 Names of Emacs's standard keymaps.
974 * Rebinding:: How to redefine one key's meaning conveniently.
975 * Disabling:: Disabling a command means confirmation is required
976 before it can be executed. This is done to protect
977 beginners from surprises.
984 @cindex global keymap
986 The bindings between characters and command functions are recorded in
987 data structures called @dfn{keymaps}. Emacs has many of these. One, the
988 @dfn{global} keymap, defines the meanings of the single-character keys that
989 are defined regardless of major mode. It is the value of the variable
994 @vindex lisp-mode-map
995 Each major mode has another keymap, its @dfn{local keymap}, which
996 contains overriding definitions for the single-character keys that are
997 redefined in that mode. Each buffer records which local keymap is
998 installed for it at any time, and the current buffer's local keymap is
999 the only one that directly affects command execution. The local keymaps
1000 for Lisp mode, C mode, and many other major modes always exist even when
1001 not in use. They are the values of the variables @code{lisp-mode-map},
1002 @code{c-mode-map}, and so on. For less frequently used major modes, the
1003 local keymap is sometimes constructed only when the mode is used for the
1004 first time in a session, to save space.
1007 @vindex minibuffer-local-map
1008 @vindex minibuffer-local-ns-map
1009 @vindex minibuffer-local-completion-map
1010 @vindex minibuffer-local-must-match-map
1011 @vindex repeat-complex-command-map
1012 @vindex isearch-mode-map
1013 There are local keymaps for the minibuffer, too; they contain various
1014 completion and exit commands.
1018 @code{minibuffer-local-map} is used for ordinary input (no completion).
1020 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1021 just like @key{RET}. This is used mainly for Mocklisp compatibility.
1023 @code{minibuffer-local-completion-map} is for permissive completion.
1025 @code{minibuffer-local-must-match-map} is for strict completion and
1026 for cautious completion.
1028 @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
1030 @code{isearch-mode-map} contains the bindings of the special keys which
1031 are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}.
1037 Finally, each prefix key has a keymap which defines the key sequences
1038 that start with it. For example, @code{ctl-x-map} is the keymap used for
1039 characters following a @kbd{C-x}.
1043 @code{ctl-x-map} is the variable name for the map used for characters that
1046 @code{help-map} is used for characters that follow @kbd{C-h}.
1048 @code{esc-map} is for characters that follow @key{ESC}. All Meta
1049 characters are actually defined by this map.
1051 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1053 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1056 The definition of a prefix key is the keymap to use for looking up
1057 the following character. Sometimes the definition is actually a Lisp
1058 symbol whose function definition is the following character keymap. The
1059 effect is the same, but it provides a command name for the prefix key that
1060 you can use as a description of what the prefix key is for. Thus the
1061 binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
1062 definition is the keymap for @kbd{C-x} commands, the value of
1063 @code{ctl-x-map}.@refill
1065 Prefix key definitions can appear in either the global
1066 map or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
1067 and @key{ESC} as prefix keys appear in the global map, so these prefix
1068 keys are always available. Major modes can locally redefine a key as a
1069 prefix by putting a prefix key definition for it in the local
1072 A mode can also put a prefix definition of a global prefix character such
1073 as @kbd{C-x} into its local map. This is how major modes override the
1074 definitions of certain keys that start with @kbd{C-x}. This case is
1075 special, because the local definition does not entirely replace the global
1076 one. When both the global and local definitions of a key are other
1077 keymaps, the next character is looked up in both keymaps, with the local
1078 definition overriding the global one. The character after the
1079 @kbd{C-x} is looked up in both the major mode's own keymap for redefined
1080 @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
1081 for @kbd{C-x} commands contains @code{nil}, the definition from the global
1082 keymap for @kbd{C-x} commands is used.@refill
1085 @subsection Changing Key Bindings
1086 @cindex key rebinding, this session
1087 @cindex rebinding keys, this session
1089 You can redefine an Emacs key by changing its entry in a keymap.
1090 You can change the global keymap, in which case the change is effective in
1091 all major modes except those that have their own overriding local
1092 definitions for the same key. Or you can change the current buffer's
1093 local map, which affects all buffers using the same major mode.
1096 * Interactive Rebinding:: Changing Key Bindings Interactively
1097 * Programmatic Rebinding:: Changing Key Bindings Programmatically
1098 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings
1101 @node Interactive Rebinding
1102 @subsubsection Changing Key Bindings Interactively
1103 @findex global-set-key
1104 @findex local-set-key
1105 @findex local-unset-key
1108 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1109 Defines @var{key} globally to run @var{cmd}.
1110 @item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET}
1111 Defines @var{key} locally (in the major mode now in effect) to run
1113 @item M-x local-unset-key @key{RET} @var{keys} @key{RET}
1114 Removes the local binding of @var{key}.
1117 @var{cmd} is a symbol naming an interactively-callable function.
1119 When called interactively, @var{key} is the next complete key sequence
1120 that you type. When called as a function, @var{key} is a string, a
1121 vector of events, or a vector of key-description lists as described in
1122 the @code{define-key} function description. The binding goes in
1123 the current buffer's local map, which is shared with other buffers in
1124 the same major mode.
1126 The following example:
1129 M-x global-set-key @key{RET} C-f next-line @key{RET}
1133 redefines @kbd{C-f} to move down a line. The fact that @var{cmd} is
1134 read second makes it serve as a kind of confirmation for @var{key}.
1136 These functions offer no way to specify a particular prefix keymap as
1137 the one to redefine in, but that is not necessary, as you can include
1138 prefixes in @var{key}. @var{key} is read by reading characters one by
1139 one until they amount to a complete key (that is, not a prefix key).
1140 Thus, if you type @kbd{C-f} for @var{key}, Emacs enters
1141 the minibuffer immediately to read @var{cmd}. But if you type
1142 @kbd{C-x}, another character is read; if that character is @kbd{4},
1143 another character is read, and so on. For example,@refill
1146 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1150 redefines @kbd{C-x 4 $} to run the (fictitious) command
1151 @code{spell-other-window}.
1154 @findex substitute-key-definition
1155 The most general way to modify a keymap is the function
1156 @code{define-key}, used in Lisp code (such as your @file{.emacs} file).
1157 @code{define-key} takes three arguments: the keymap, the key to modify
1158 in it, and the new definition. @xref{Init File}, for an example.
1159 @code{substitute-key-definition} is used similarly; it takes three
1160 arguments, an old definition, a new definition, and a keymap, and
1161 redefines in that keymap all keys that were previously defined with the
1162 old definition to have the new definition instead.
1164 @node Programmatic Rebinding
1165 @subsubsection Changing Key Bindings Programmatically
1167 You can use the functions @code{global-set-key} and @code{define-key}
1168 to rebind keys under program control.
1171 @findex global-set-key
1174 @item @code{(global-set-key @var{keys} @var{cmd})}
1175 Defines @var{keys} globally to run @var{cmd}.
1176 @item @code{(define-key @var{keymap} @var{keys} @var{def})}
1177 Defines @var{keys} to run @var{def} in the keymap @var{keymap}.
1180 @var{keymap} is a keymap object.
1182 @var{keys} is the sequence of keystrokes to bind.
1184 @var{def} is anything that can be a key's definition:
1188 @code{nil}, meaning key is undefined in this keymap
1190 A command, that is, a Lisp function suitable for interactive calling
1192 A string or key sequence vector, which is treated as a keyboard macro
1194 A keymap to define a prefix key
1196 A symbol so that when the key is looked up, the symbol stands for its
1197 function definition, which should at that time be one of the above,
1198 or another symbol whose function definition is used, and so on
1200 A cons, @code{(string . defn)}, meaning that @var{defn} is the definition
1201 (@var{defn} should be a valid definition in its own right)
1203 A cons, @code{(keymap . char)}, meaning use the definition of
1204 @var{char} in map @var{keymap}
1207 For backward compatibility, XEmacs allows you to specify key
1208 sequences as strings. However, the preferred method is to use the
1209 representations of key sequences as vectors of keystrokes.
1210 @xref{Keystrokes}, for more information about the rules for constructing
1213 Emacs allows you to abbreviate representations for key sequences in
1214 most places where there is no ambiguity.
1215 Here are some rules for abbreviation:
1219 The keysym by itself is equivalent to a list of just that keysym, i.e.,
1220 @code{f1} is equivalent to @code{(f1)}.
1222 A keystroke by itself is equivalent to a vector containing just that
1223 keystroke, i.e., @code{(control a)} is equivalent to @code{[(control a)]}.
1225 You can use ASCII codes for keysyms that have them. i.e.,
1226 @code{65} is equivalent to @code{A}. (This is not so much an
1227 abbreviation as an alternate representation.)
1230 Here are some examples of programmatically binding keys:
1234 ;;; Bind @code{my-command} to @key{f1}
1235 (global-set-key 'f1 'my-command)
1237 ;;; Bind @code{my-command} to @kbd{Shift-f1}
1238 (global-set-key '(shift f1) 'my-command)
1240 ;;; Bind @code{my-command} to @kbd{C-c Shift-f1}
1241 (global-set-key '[(control c) (shift f1)] 'my-command)
1243 ;;; Bind @code{my-command} to the middle mouse button.
1244 (global-set-key 'button2 'my-command)
1246 ;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}}
1247 ;;; in the keymap that is in force when you are running @code{dired}.
1248 (define-key dired-mode-map '(meta control button3) 'my-command)
1252 @comment ;; note that these next four lines are not synonymous:
1254 @comment (global-set-key '(meta control delete) 'my-command)
1255 @comment (global-set-key '(meta control backspace) 'my-command)
1256 @comment (global-set-key '(meta control h) 'my-command)
1257 @comment (global-set-key '(meta control H) 'my-command)
1259 @comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''.
1261 @comment (global-set-key "\^J" 'my-command)
1263 @node Key Bindings Using Strings
1264 @subsubsection Using Strings for Changing Key Bindings
1266 For backward compatibility, you can still use strings to represent
1267 key sequences. Thus you can use commands like the following:
1270 ;;; Bind @code{end-of-line} to @kbd{C-f}
1271 (global-set-key "\C-f" 'end-of-line)
1274 Note, however, that in some cases you may be binding more than one
1275 key sequence by using a single command. This situation can
1276 arise because in ASCII, @kbd{C-i} and @key{TAB} have
1277 the same representation. Therefore, when Emacs sees:
1280 (global-set-key "\C-i" 'end-of-line)
1283 it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}.
1284 The solution XEmacs adopts is to bind both of these key
1287 @cindex redefining keys
1288 After binding a command to two key sequences with a form like:
1291 (define-key global-map "\^X\^I" 'command-1)
1294 it is possible to redefine only one of those sequences like so:
1297 (define-key global-map [(control x) (control i)] 'command-2)
1298 (define-key global-map [(control x) tab] 'command-3)
1301 This applies only when running under a window system. If you are
1302 talking to Emacs through an ASCII-only channel, you do not get any of
1305 Here is a table of pairs of key sequences that behave in a
1315 control @@ control space
1319 @subsection Disabling Commands
1320 @cindex disabled command
1322 Disabling a command marks it as requiring confirmation before it
1323 can be executed. The purpose of disabling a command is to prevent
1324 beginning users from executing it by accident and being confused.
1326 The direct mechanism for disabling a command is to have a non-@code{nil}
1327 @code{disabled} property on the Lisp symbol for the command. These
1328 properties are normally set by the user's @file{.emacs} file with
1329 Lisp expressions such as:
1332 (put 'delete-region 'disabled t)
1335 If the value of the @code{disabled} property is a string, that string
1336 is included in the message printed when the command is used:
1339 (put 'delete-region 'disabled
1340 "Text deleted this way cannot be yanked back!\n")
1343 @findex disable-command
1344 @findex enable-command
1345 You can disable a command either by editing the @file{.emacs} file
1346 directly or with the command @kbd{M-x disable-command}, which edits the
1347 @file{.emacs} file for you. @xref{Init File}.
1349 When you attempt to invoke a disabled command interactively in Emacs,
1350 a window is displayed containing the command's name, its
1351 documentation, and some instructions on what to do next; then
1352 Emacs asks for input saying whether to execute the command as requested,
1353 enable it and execute, or cancel it. If you decide to enable the
1354 command, you are asked whether to do this permanently or just for the
1355 current session. Enabling permanently works by automatically editing
1356 your @file{.emacs} file. You can use @kbd{M-x enable-command} at any
1357 time to enable any command permanently.
1359 Whether a command is disabled is independent of what key is used to
1360 invoke it; it also applies if the command is invoked using @kbd{M-x}.
1361 Disabling a command has no effect on calling it as a function from Lisp
1365 @section The Syntax Table
1366 @cindex syntax table
1368 All the Emacs commands which parse words or balance parentheses are
1369 controlled by the @dfn{syntax table}. The syntax table specifies which
1370 characters are opening delimiters, which are parts of words, which are
1371 string quotes, and so on. Actually, each major mode has its own syntax
1372 table (though sometimes related major modes use the same one) which it
1373 installs in each buffer that uses that major mode. The syntax table
1374 installed in the current buffer is the one that all commands use, so we
1375 call it ``the'' syntax table. A syntax table is a Lisp object, a vector of
1376 length 256 whose elements are numbers.
1379 * Entry: Syntax Entry. What the syntax table records for each character.
1380 * Change: Syntax Change. How to change the information.
1384 @subsection Information About Each Character
1386 The syntax table entry for a character is a number that encodes six
1387 pieces of information:
1391 The syntactic class of the character, represented as a small integer
1393 The matching delimiter, for delimiter characters only
1394 (the matching delimiter of @samp{(} is @samp{)}, and vice versa)
1396 A flag saying whether the character is the first character of a
1397 two-character comment starting sequence
1399 A flag saying whether the character is the second character of a
1400 two-character comment starting sequence
1402 A flag saying whether the character is the first character of a
1403 two-character comment ending sequence
1405 A flag saying whether the character is the second character of a
1406 two-character comment ending sequence
1409 The syntactic classes are stored internally as small integers, but are
1410 usually described to or by the user with characters. For example, @samp{(}
1411 is used to specify the syntactic class of opening delimiters. Here is a
1412 table of syntactic classes, with the characters that specify them.
1416 The class of whitespace characters.
1418 The class of word-constituent characters.
1420 The class of characters that are part of symbol names but not words.
1421 This class is represented by @samp{_} because the character @samp{_}
1422 has this class in both C and Lisp.
1424 The class of punctuation characters that do not fit into any other
1427 The class of opening delimiters.
1429 The class of closing delimiters.
1431 The class of expression-adhering characters. These characters are
1432 part of a symbol if found within or adjacent to one, and are part
1433 of a following expression if immediately preceding one, but are like
1434 whitespace if surrounded by whitespace.
1436 The class of string-quote characters. They match each other in pairs,
1437 and the characters within the pair all lose their syntactic
1438 significance except for the @samp{\} and @samp{/} classes of escape
1439 characters, which can be used to include a string-quote inside the
1442 The class of self-matching delimiters. This is intended for @TeX{}'s
1443 @samp{$}, which is used both to enter and leave math mode. Thus,
1444 a pair of matching @samp{$} characters surround each piece of math mode
1445 @TeX{} input. A pair of adjacent @samp{$} characters act like a single
1446 one for purposes of matching.
1449 The class of escape characters that always just deny the following
1450 character its special syntactic significance. The character after one
1451 of these escapes is always treated as alphabetic.
1453 The class of C-style escape characters. In practice, these are
1454 treated just like @samp{/}-class characters, because the extra
1455 possibilities for C escapes (such as being followed by digits) have no
1456 effect on where the containing expression ends.
1458 The class of comment-starting characters. Only single-character
1459 comment starters (such as @samp{;} in Lisp mode) are represented this
1462 The class of comment-ending characters. Newline has this syntax in
1466 @vindex parse-sexp-ignore-comments
1467 The characters flagged as part of two-character comment delimiters can
1468 have other syntactic functions most of the time. For example, @samp{/} and
1469 @samp{*} in C code, when found separately, have nothing to do with
1470 comments. The comment-delimiter significance overrides when the pair of
1471 characters occur together in the proper order. Only the list and sexp
1472 commands use the syntax table to find comments; the commands specifically
1473 for comments have other variables that tell them where to find comments.
1474 Moreover, the list and sexp commands notice comments only if
1475 @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
1476 to @code{nil} in modes where comment-terminator sequences are liable to
1477 appear where there is no comment, for example, in Lisp mode where the
1478 comment terminator is a newline but not every newline ends a comment.
1481 @subsection Altering Syntax Information
1483 It is possible to alter a character's syntax table entry by storing a new
1484 number in the appropriate element of the syntax table, but it would be hard
1485 to determine what number to use. Emacs therefore provides a command that
1486 allows you to specify the syntactic properties of a character in a
1489 @findex modify-syntax-entry
1490 @kbd{M-x modify-syntax-entry} is the command to change a character's
1491 syntax. It can be used interactively and is also used by major
1492 modes to initialize their own syntax tables. Its first argument is the
1493 character to change. The second argument is a string that specifies the
1494 new syntax. When called from Lisp code, there is a third, optional
1495 argument, which specifies the syntax table in which to make the change. If
1496 not supplied, or if this command is called interactively, the third
1497 argument defaults to the current buffer's syntax table.
1501 The first character in the string specifies the syntactic class. It
1502 is one of the characters in the previous table (@pxref{Syntax Entry}).
1505 The second character is the matching delimiter. For a character that
1506 is not an opening or closing delimiter, this should be a space, and may
1507 be omitted if no following characters are needed.
1510 The remaining characters are flags. The flag characters allowed are:
1514 Flag this character as the first of a two-character comment starting sequence.
1516 Flag this character as the second of a two-character comment starting sequence.
1518 Flag this character as the first of a two-character comment ending sequence.
1520 Flag this character as the second of a two-character comment ending sequence.
1525 @findex describe-syntax
1526 Use @kbd{C-h s} (@code{describe-syntax}) to display a description of
1527 the contents of the current syntax table. The description of each
1528 character includes both the string you have to pass to
1529 @code{modify-syntax-entry} to set up that character's current syntax,
1530 and some English to explain that string if necessary.
1533 @section The Init File, .emacs
1535 @cindex Emacs initialization file
1536 @cindex key rebinding, permanent
1537 @cindex rebinding keys, permanently
1539 When you start Emacs, it normally loads the file @file{.emacs} in your
1540 home directory. This file, if it exists, should contain Lisp code. It
1541 is called your initialization file or @dfn{init file}. Use the command
1542 line switch @samp{-q} to tell Emacs whether to load an
1543 init file (@pxref{Entering Emacs}). Use the command line switch
1544 @samp{-user-init-file} (@pxref{Command Switches}) to tell Emacs to load
1545 a different file instead of @file{~/.emacs}.
1547 When the @file{.emacs} file is read, the variable @code{user-init-file}
1548 says which init file was loaded.
1550 At some sites there is a @dfn{default init file}, which is the
1551 library named @file{default.el}, found via the standard search path for
1552 libraries. The Emacs distribution contains no such library; your site
1553 may create one for local customizations. If this library exists, it is
1554 loaded whenever you start Emacs. But your init file, if any, is loaded
1555 first; if it sets @code{inhibit-default-init} non-@code{nil}, then
1556 @file{default} is not loaded.
1558 If you have a large amount of code in your @file{.emacs} file, you
1559 should move it into another file named @file{@var{something}.el},
1560 byte-compile it (@pxref{Lisp Libraries}), and load that file from your
1561 @file{.emacs} file using @code{load}.
1564 * Init Syntax:: Syntax of constants in Emacs Lisp.
1565 * Init Examples:: How to do some things with an init file.
1566 * Terminal Init:: Each terminal type can have an init file.
1570 @subsection Init File Syntax
1572 The @file{.emacs} file contains one or more Lisp function call
1573 expressions. Each consists of a function name followed by
1574 arguments, all surrounded by parentheses. For example, @code{(setq
1575 fill-column 60)} represents a call to the function @code{setq} which is
1576 used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
1578 The second argument to @code{setq} is an expression for the new value
1579 of the variable. This can be a constant, a variable, or a function call
1580 expression. In @file{.emacs}, constants are used most of the time.
1585 Integers are written in decimal, with an optional initial minus sign.
1587 If a sequence of digits is followed by a period and another sequence
1588 of digits, it is interpreted as a floating point number.
1590 The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to
1591 represent numbers in binary, octal, and hexadecimal notation (or radix).
1594 Lisp string syntax is the same as C string syntax with a few extra
1595 features. Use a double-quote character to begin and end a string constant.
1597 Newlines and special characters may be present literally in strings. They
1598 can also be represented as backslash sequences: @samp{\n} for newline,
1599 @samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab,
1600 @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
1601 backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
1602 character whose octal code is @var{ooo}. Backslash and double-quote are
1603 the only characters for which backslash sequences are mandatory.
1605 You can use @samp{\C-} as a prefix for a control character, as in
1606 @samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for
1607 a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
1608 Control-Meta-A.@refill
1611 Lisp character constant syntax consists of a @samp{?} followed by
1612 either a character or an escape sequence starting with @samp{\}.
1613 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
1614 strings and characters are not interchangeable in Lisp; some contexts
1615 require one and some contexts require the other.
1618 @code{t} stands for `true'.
1621 @code{nil} stands for `false'.
1623 @item Other Lisp objects
1624 Write a single-quote (') followed by the Lisp object you want.
1628 @subsection Init File Examples
1630 Here are some examples of doing certain commonly desired things with
1635 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
1639 (setq c-tab-always-indent nil)
1642 Here we have a variable whose value is normally @code{t} for `true'
1643 and the alternative is @code{nil} for `false'.
1646 Make searches case sensitive by default (in all buffers that do not
1650 (setq-default case-fold-search nil)
1653 This sets the default value, which is effective in all buffers that do
1654 not have local values for the variable. Setting @code{case-fold-search}
1655 with @code{setq} affects only the current buffer's local value, which
1656 is probably not what you want to do in an init file.
1659 Make Text mode the default mode for new buffers.
1662 (setq default-major-mode 'text-mode)
1665 Note that @code{text-mode} is used because it is the command for entering
1666 the mode we want. A single-quote is written before it to make a symbol
1667 constant; otherwise, @code{text-mode} would be treated as a variable name.
1670 Turn on Auto Fill mode automatically in Text mode and related modes.
1673 (setq text-mode-hook
1674 '(lambda () (auto-fill-mode 1)))
1677 Here we have a variable whose value should be a Lisp function. The
1678 function we supply is a list starting with @code{lambda}, and a single
1679 quote is written in front of it to make it (for the purpose of this
1680 @code{setq}) a list constant rather than an expression. Lisp functions
1681 are not explained here; for mode hooks it is enough to know that
1682 @code{(auto-fill-mode 1)} is an expression that will be executed when
1683 Text mode is entered. You could replace it with any other expression
1684 that you like, or with several expressions in a row.
1687 (setq text-mode-hook 'turn-on-auto-fill)
1690 This is another way to accomplish the same result.
1691 @code{turn-on-auto-fill} is a symbol whose function definition is
1692 @code{(lambda () (auto-fill-mode 1))}.
1695 Load the installed Lisp library named @file{foo} (actually a file
1696 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
1702 When the argument to @code{load} is a relative pathname, not starting
1703 with @samp{/} or @samp{~}, @code{load} searches the directories in
1704 @code{load-path} (@pxref{Loading}).
1707 Load the compiled Lisp file @file{foo.elc} from your home directory.
1713 Here an absolute file name is used, so no searching is done.
1716 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
1719 (global-set-key "\C-xl" 'make-symbolic-link)
1725 (define-key global-map "\C-xl" 'make-symbolic-link)
1728 Note once again the single-quote used to refer to the symbol
1729 @code{make-symbolic-link} instead of its value as a variable.
1732 Do the same thing for C mode only.
1735 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
1739 Bind the function key @key{F1} to a command in C mode.
1740 Note that the names of function keys must be lower case.
1743 (define-key c-mode-map 'f1 'make-symbolic-link)
1747 Bind the shifted version of @key{F1} to a command.
1750 (define-key c-mode-map '(shift f1) 'make-symbolic-link)
1754 Redefine all keys which now run @code{next-line} in Fundamental mode
1755 to run @code{forward-line} instead.
1758 (substitute-key-definition 'next-line 'forward-line
1763 Make @kbd{C-x C-v} undefined.
1766 (global-unset-key "\C-x\C-v")
1769 One reason to undefine a key is so that you can make it a prefix.
1770 Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
1771 a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
1775 Make @samp{$} have the syntax of punctuation in Text mode.
1776 Note the use of a character constant for @samp{$}.
1779 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
1783 Enable the use of the command @code{eval-expression} without confirmation.
1786 (put 'eval-expression 'disabled nil)
1791 @subsection Terminal-Specific Initialization
1793 Each terminal type can have a Lisp library to be loaded into Emacs when
1794 it is run on that type of terminal. For a terminal type named
1795 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
1796 found by searching the directories @code{load-path} as usual and trying the
1797 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
1798 subdirectory @file{term} of the directory where most Emacs libraries are
1801 The usual purpose of the terminal-specific library is to define the
1802 escape sequences used by the terminal's function keys using the library
1803 @file{keypad.el}. See the file
1804 @file{term/vt100.el} for an example of how this is done.@refill
1806 When the terminal type contains a hyphen, only the part of the name
1807 before the first hyphen is significant in choosing the library name.
1808 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
1809 the library @file{term/aaa}. The code in the library can use
1810 @code{(getenv "TERM")} to find the full terminal type name.@refill
1812 @vindex term-file-prefix
1813 The library's name is constructed by concatenating the value of the
1814 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
1815 file can prevent the loading of the terminal-specific library by setting
1816 @code{term-file-prefix} to @code{nil}.
1818 @vindex term-setup-hook
1819 The value of the variable @code{term-setup-hook}, if not @code{nil}, is
1820 called as a function of no arguments at the end of Emacs initialization,
1821 after both your @file{.emacs} file and any terminal-specific library have
1822 been read. You can set the value in the @file{.emacs} file to override
1823 part of any of the terminal-specific libraries and to define
1824 initializations for terminals that do not have a library.@refill
1827 @section Changing the Bell Sound
1828 @cindex audible bell, changing
1829 @cindex bell, changing
1831 @findex load-default-sounds
1834 You can now change how the audible bell sounds using the variable
1837 @code{sound-alist}'s value is an list associating symbols with, among
1838 other things, strings of audio-data. When @code{ding} is called with
1839 one of the symbols, the associated sound data is played instead of the
1840 standard beep. This only works if you are logged in on the console of a
1841 machine with audio hardware. To listen to a sound of the provided type,
1842 call the function @code{play-sound} with the argument @var{sound}. You
1843 can also set the volume of the sound with the optional argument
1844 @var{volume}.@refill
1847 Each element of @code{sound-alist} is a list describing a sound.
1848 The first element of the list is the name of the sound being defined.
1849 Subsequent elements of the list are alternating keyword/value pairs:
1853 A string of raw sound data, or the name of another sound to play.
1854 The symbol @code{t} here means use the default X beep.
1857 An integer from 0-100, defaulting to @code{bell-volume}.
1860 If using the default X beep, the pitch (Hz) to generate.
1863 If using the default X beep, the duration (milliseconds).
1866 For compatibility, elements of `sound-alist' may also be of the form:
1869 ( @var{sound-name} . @var{<sound>} )
1870 ( @var{sound-name} @var{<volume>} @var{<sound>} )
1873 You should probably add things to this list by calling the function
1874 @code{load-sound-file}.
1876 Note that you can only play audio data if running on the console screen
1877 of a machine with audio hardware which emacs understands, which at this
1878 time means a Sun SparcStation, SGI, or HP9000s700.
1880 Also note that the pitch, duration, and volume options are available
1881 everywhere, but most X servers ignore the `pitch' option.
1884 The variable @code{bell-volume} should be an integer from 0 to 100,
1885 with 100 being loudest, which controls how loud the sounds emacs makes
1886 should be. Elements of the @code{sound-alist} may override this value.
1887 This variable applies to the standard X bell sound as well as sound files.
1889 If the symbol @code{t} is in place of a sound-string, Emacs uses the
1890 default X beep. This allows you to define beep-types of
1891 different volumes even when not running on the console.
1893 @findex load-sound-file
1894 You can add things to this list by calling the function
1895 @code{load-sound-file}, which reads in an audio-file and adds its data to
1896 the sound-alist. You can specify the sound with the @var{sound-name}
1897 argument and the file into which the sounds are loaded with the
1898 @var{filename} argument. The optional @var{volume} argument sets the
1901 @code{load-sound-file (@var{filename sound-name} &optional @var{volume})}
1903 To load and install some sound files as beep-types, use the function
1904 @code{load-default-sounds} (note that this only works if you are on
1905 display 0 of a machine with audio hardware).
1907 The following beep-types are used by Emacs itself. Other Lisp
1908 packages may use other beep types, but these are the ones that the C
1909 kernel of Emacs uses.
1912 @item auto-save-error
1913 An auto-save does not succeed
1916 The Emacs command loop catches an error
1919 You type a key that is undefined
1921 @item undefined-click
1922 You use an undefined mouse-click combination
1925 Completion was not possible
1928 You type something other than the required @code{y} or @code{n}
1931 You type something other than @code{yes} or @code{no}
1934 @comment node-name, next, previous, up
1938 XEmacs has objects called extents and faces. An @dfn{extent}
1939 is a region of text and a @dfn{face} is a collection of textual
1940 attributes, such as fonts and colors. Every extent is displayed in some
1941 face; therefore, changing the properties of a face immediately updates the
1942 display of all associated extents. Faces can be frame-local: you can
1943 have a region of text that displays with completely different
1944 attributes when its buffer is viewed from a different X window.
1946 The display attributes of faces may be specified either in Lisp or through
1947 the X resource manager.
1949 @subsection Customizing Faces
1951 You can change the face of an extent with the functions in
1952 this section. All the functions prompt for a @var{face} as an
1953 argument; use completion for a list of possible values.
1956 @item M-x invert-face
1957 Swap the foreground and background colors of the given @var{face}.
1958 @item M-x make-face-bold
1959 Make the font of the given @var{face} bold. When called from a
1960 program, returns @code{nil} if this is not possible.
1961 @item M-x make-face-bold-italic
1962 Make the font of the given @var{face} bold italic.
1963 When called from a program, returns @code{nil} if not possible.
1964 @item M-x make-face-italic
1965 Make the font of the given @var{face} italic.
1966 When called from a program, returns @code{nil} if not possible.
1967 @item M-x make-face-unbold
1968 Make the font of the given @var{face} non-bold.
1969 When called from a program, returns @code{nil} if not possible.
1970 @item M-x make-face-unitalic
1971 Make the font of the given @var{face} non-italic.
1972 When called from a program, returns @code{nil} if not possible.
1973 @item M-x make-face-larger
1974 Make the font of the given @var{face} a little larger.
1975 When called from a program, returns @code{nil} if not possible.
1976 @item M-x make-face-smaller
1977 Make the font of the given @var{face} a little smaller.
1978 When called from a program, returns @code{nil} if not possible.
1979 @item M-x set-face-background
1980 Change the background color of the given @var{face}.
1981 @item M-x set-face-background-pixmap
1982 Change the background pixmap of the given @var{face}.
1983 @item M-x set-face-font
1984 Change the font of the given @var{face}.
1985 @item M-x set-face-foreground
1986 Change the foreground color of the given @var{face}.
1987 @item M-x set-face-underline-p
1988 Change whether the given @var{face} is underlined.
1991 @findex make-face-bold
1992 @findex make-face-bold-italic
1993 @findex make-face-italic
1994 @findex make-face-unbold
1995 @findex make-face-unitalic
1996 @findex make-face-larger
1997 @findex make-face-smaller
2000 You can exchange the foreground and background color of the selected
2001 @var{face} with the function @code{invert-face}. If the face does not
2002 specify both foreground and background, then its foreground and
2003 background are set to the background and foreground of the default face.
2004 When calling this from a program, you can supply the optional argument
2005 @var{frame} to specify which frame is affected; otherwise, all frames
2008 @findex set-face-background
2009 You can set the background color of the specified @var{face} with the
2010 function @code{set-face-background}. The argument @code{color} should
2011 be a string, the name of a color. When called from a program, if the
2012 optional @var{frame} argument is provided, the face is changed only
2013 in that frame; otherwise, it is changed in all frames.
2015 @findex set-face-background-pixmap
2016 You can set the background pixmap of the specified @var{face} with the
2017 function @code{set-face-background-pixmap}. The pixmap argument
2018 @var{name} should be a string, the name of a file of pixmap data. The
2019 directories listed in the @code{x-bitmap-file-path} variable are
2020 searched. The bitmap may also be a list of the form @code{(@var{width
2021 height data})}, where @var{width} and @var{height} are the size in
2022 pixels, and @var{data} is a string containing the raw bits of the
2023 bitmap. If the optional @var{frame} argument is provided, the face is
2024 changed only in that frame; otherwise, it is changed in all frames.
2026 The variable @code{x-bitmap-file-path} takes as a value a list of the
2027 directories in which X bitmap files may be found. If the value is
2028 @code{nil}, the list is initialized from the @code{*bitmapFilePath}
2031 If the environment variable @b{XBMLANGPATH} is set, then it is consulted
2032 before the @code{x-bitmap-file-path} variable.
2034 @findex set-face-font
2035 You can set the font of the specified @var{face} with the function
2036 @code{set-face-font}. The @var{font} argument should be a string, the
2037 name of a font. When called from a program, if the
2038 optional @var{frame} argument is provided, the face is changed only
2039 in that frame; otherwise, it is changed in all frames.
2041 @findex set-face-foreground
2042 You can set the foreground color of the specified @var{face} with the
2043 function @code{set-face-foreground}. The argument @var{color} should be
2044 a string, the name of a color. If the optional @var{frame} argument is
2045 provided, the face is changed only in that frame; otherwise, it is
2046 changed in all frames.
2048 @findex set-face-underline-p
2049 You can set underline the specified @var{face} with the function
2050 @code{set-face-underline-p}. The argument @var{underline-p} can be used
2051 to make underlining an attribute of the face or not. If the optional
2052 @var{frame} argument is provided, the face is changed only in that
2053 frame; otherwise, it is changed in all frames.
2056 @section X Resources
2058 @findex x-create-frame
2060 Historically, XEmacs has used the X resource application class @samp{Emacs}
2061 for its resources. Unfortunately, GNU Emacs uses the same application
2062 class, and resources are not compatible between the two Emacsen. This
2063 sharing of the application class often leads to trouble if you want to
2066 Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
2067 any XEmacs resources in the resource database when the X connection is
2068 initialized. Otherwise, it will use the class @samp{Emacs} for
2069 backwards compatability. The variable @var{x-emacs-application-class}
2070 may be consulted to determine the application class being used.
2072 The examples in this section assume the application class is @samp{Emacs}.
2074 The Emacs resources are generally set per-frame. Each Emacs frame can have
2075 its own name or the same name as another, depending on the name passed to the
2076 @code{make-frame} function.
2078 You can specify resources for all frames with the syntax:
2081 Emacs*parameter: value
2088 Emacs*EmacsFrame.parameter:value
2092 You can specify resources for a particular frame with the syntax:
2095 Emacs*FRAME-NAME.parameter: value
2100 * Geometry Resources:: Controlling the size and position of frames.
2101 * Iconic Resources:: Controlling whether frames come up iconic.
2102 * Resource List:: List of resources settable on a frame or device.
2103 * Face Resources:: Controlling faces using resources.
2104 * Widgets:: The widget hierarchy for XEmacs.
2105 * Menubar Resources:: Specifying resources for the menubar.
2108 @node Geometry Resources
2109 @subsection Geometry Resources
2111 To make the default size of all Emacs frames be 80 columns by 55 lines,
2115 Emacs*EmacsFrame.geometry: 80x55
2119 To set the geometry of a particular frame named @samp{fred}, do this:
2122 Emacs*fred.geometry: 80x55
2126 Important! Do not use the following syntax:
2129 Emacs*geometry: 80x55
2133 You should never use @code{*geometry} with any X application. It does
2134 not say "make the geometry of Emacs be 80 columns by 55 lines." It
2135 really says, "make Emacs and all subwindows thereof be 80x55 in whatever
2136 units they care to measure in." In particular, that is both telling the
2137 Emacs text pane to be 80x55 in characters, and telling the menubar pane
2138 to be 80x55 pixels, which is surely not what you want.
2140 As a special case, this geometry specification also works (and sets the
2141 default size of all Emacs frames to 80 columns by 55 lines):
2144 Emacs.geometry: 80x55
2148 since that is the syntax used with most other applications (since most
2149 other applications have only one top-level window, unlike Emacs). In
2150 general, however, the top-level shell (the unmapped ApplicationShell
2151 widget named @samp{Emacs} that is the parent of the shell widgets that
2152 actually manage the individual frames) does not have any interesting
2153 resources on it, and you should set the resources on the frames instead.
2155 The @code{-geometry} command-line argument sets only the geometry of the
2156 initial frame created by Emacs.
2158 A more complete explanation of geometry-handling is
2162 The @code{-geometry} command-line option sets the @code{Emacs.geometry}
2163 resource, that is, the geometry of the ApplicationShell.
2166 For the first frame created, the size of the frame is taken from the
2167 ApplicationShell if it is specified, otherwise from the geometry of the
2171 For subsequent frames, the order is reversed: First the frame, and then
2172 the ApplicationShell.
2175 For the first frame created, the position of the frame is taken from the
2176 ApplicationShell (@code{Emacs.geometry}) if it is specified, otherwise
2177 from the geometry of the frame.
2180 For subsequent frames, the position is taken only from the frame, and
2181 never from the ApplicationShell.
2184 This is rather complicated, but it does seem to provide the most
2185 intuitive behavior with respect to the default sizes and positions of
2186 frames created in various ways.
2188 @node Iconic Resources
2189 @subsection Iconic Resources
2191 Analogous to @code{-geometry}, the @code{-iconic} command-line option
2192 sets the iconic flag of the ApplicationShell (@code{Emacs.iconic}) and
2193 always applies to the first frame created regardless of its name.
2194 However, it is possible to set the iconic flag on particular frames (by
2195 name) by using the @code{Emacs*FRAME-NAME.iconic} resource.
2198 @subsection Resource List
2200 Emacs frames accept the following resources:
2203 @item @code{geometry} (class @code{Geometry}): string
2204 Initial geometry for the frame. @xref{Geometry Resources}, for a
2205 complete discussion of how this works.
2207 @item @code{iconic} (class @code{Iconic}): boolean
2208 Whether this frame should appear in the iconified state.
2210 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int
2211 How many blank pixels to leave between the text and the edge of the
2214 @item @code{interline} (class @code{Interline}): int
2215 How many pixels to leave between each line (may not be implemented).
2217 @item @code{menubar} (class @code{Menubar}): boolean
2218 Whether newly-created frames should initially have a menubar. Set to
2221 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean
2222 Whether XEmacs should leave the initial frame unmapped when it starts
2223 up. This is useful if you are starting XEmacs as a server (e.g. in
2224 conjunction with gnuserv or the external client widget). You can also
2225 control this with the @code{-unmapped} command-line option.
2227 @item @code{barCursor} (class @code{BarColor}): boolean
2228 Whether the cursor should be displayed as a bar, or the traditional box.
2230 @item @code{cursorColor} (class @code{CursorColor}): color-name
2231 The color of the text cursor.
2233 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer
2234 How wide the vertical scrollbars should be, in pixels; 0 means no
2235 vertical scrollbars. You can also use a resource specification of the
2236 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources:
2237 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid),
2238 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you
2239 use the toolkit resources, though, because they're dependent on how
2240 exactly your particular build of XEmacs was configured.
2242 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer
2243 How high the horizontal scrollbars should be, in pixels; 0 means no
2244 horizontal scrollbars. You can also use a resource specification of the
2245 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources:
2246 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid),
2247 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you use
2248 the toolkit resources, though, because they're dependent on how exactly
2249 your particular build of XEmacs was configured.
2251 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string
2252 Where the horizontal and vertical scrollbars should be positioned. This
2253 should be one of the four strings @samp{BOTTOM_LEFT},
2254 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}. Default is
2255 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and
2256 @samp{BOTTOM_LEFT} for the Athena scrollbars.
2258 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer
2259 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer
2260 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer
2261 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer
2262 Height and width of the four possible toolbars.
2264 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name
2265 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name
2266 Color of the top and bottom shadows for the toolbars. NOTE: These resources
2267 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the
2268 toolbars at the top and bottom of the frame)! Rather, they affect the top
2269 and bottom shadows around the edges of all four kinds of toolbars.
2271 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name
2272 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name
2273 Pixmap of the top and bottom shadows for the toolbars. If set, these
2274 resources override the corresponding color resources. NOTE: These
2275 resources do @emph{not} have anything to do with the top and bottom
2276 toolbars (i.e. the toolbars at the top and bottom of the frame)!
2277 Rather, they affect the top and bottom shadows around the edges of all
2278 four kinds of toolbars.
2280 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer
2281 Thickness of the shadows around the toolbars, in pixels.
2283 @item @code{visualBell} (class @code{VisualBell}): boolean
2284 Whether XEmacs should flash the screen rather than making an audible beep.
2286 @item @code{bellVolume} (class @code{BellVolume}): integer
2287 Volume of the audible beep.
2289 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean
2290 Whether XEmacs should set the backing-store attribute of the X windows
2291 it creates. This increases the memory usage of the X server but decreases
2292 the amount of X traffic necessary to update the screen, and is useful
2293 when the connection to the X server goes over a low-bandwidth line
2294 such as a modem connection.
2297 Emacs devices accept the following resources:
2300 @item @code{textPointer} (class @code{Cursor}): cursor-name
2301 The cursor to use when the mouse is over text. This resource is used to
2302 initialize the variable @code{x-pointer-shape}.
2304 @item @code{selectionPointer} (class @code{Cursor}): cursor-name
2305 The cursor to use when the mouse is over a selectable text region (an
2306 extent with the @samp{highlight} property; for example, an Info
2307 cross-reference). This resource is used to initialize the variable
2308 @code{x-selection-pointer-shape}.
2310 @item @code{spacePointer} (class @code{Cursor}): cursor-name
2311 The cursor to use when the mouse is over a blank space in a buffer (that
2312 is, after the end of a line or after the end-of-file). This resource is
2313 used to initialize the variable @code{x-nontext-pointer-shape}.
2315 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name
2316 The cursor to use when the mouse is over a modeline. This resource is
2317 used to initialize the variable @code{x-mode-pointer-shape}.
2319 @item @code{gcPointer} (class @code{Cursor}): cursor-name
2320 The cursor to display when a garbage-collection is in progress. This
2321 resource is used to initialize the variable @code{x-gc-pointer-shape}.
2323 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name
2324 The cursor to use when the mouse is over the scrollbar. This resource
2325 is used to initialize the variable @code{x-scrollbar-pointer-shape}.
2327 @item @code{pointerColor} (class @code{Foreground}): color-name
2328 @itemx @code{pointerBackground} (class @code{Background}): color-name
2329 The foreground and background colors of the mouse cursor. These
2330 resources are used to initialize the variables
2331 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}.
2334 @node Face Resources
2335 @subsection Face Resources
2337 The attributes of faces are also per-frame. They can be specified as:
2340 Emacs.FACE_NAME.parameter: value
2347 Emacs*FRAME_NAME.FACE_NAME.parameter: value
2351 Faces accept the following resources:
2354 @item @code{attributeFont} (class @code{AttributeFont}): font-name
2355 The font of this face.
2357 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name
2358 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name
2359 The foreground and background colors of this face.
2361 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name
2362 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of Emacs
2363 supports @sc{xpm}), to use as a background stipple.
2365 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean
2366 Whether text in this face should be underlined.
2369 All text is displayed in some face, defaulting to the face named
2370 @code{default}. To set the font of normal text, use
2371 @code{Emacs*default.attributeFont}. To set it in the frame named
2372 @code{fred}, use @code{Emacs*fred.default.attributeFont}.
2374 These are the names of the predefined faces:
2378 Everything inherits from this.
2381 If this is not specified in the resource database, Emacs tries to find a
2382 bold version of the font of the default face.
2385 If this is not specified in the resource database, Emacs tries to find
2386 an italic version of the font of the default face.
2389 If this is not specified in the resource database, Emacs tries to find a
2390 bold-italic version of the font of the default face.
2393 This is the face that the modeline is displayed in. If not specified in
2394 the resource database, it is determined from the default face by
2395 reversing the foreground and background colors.
2398 This is the face that highlighted extents (for example, Info
2399 cross-references and possible completions, when the mouse passes over
2400 them) are displayed in.
2404 These are the faces that the left and right annotation margins are
2408 This is the face that mouse selections are displayed in.
2411 This is the face that the matched text being searched for is displayed
2415 This is the face of info menu items. If unspecified, it is copied from
2419 This is the face of info cross-references. If unspecified, it is copied
2420 from @code{bold}. (Note that, when the mouse passes over a
2421 cross-reference, the cross-reference's face is determined from a
2422 combination of the @code{info-xref} and @code{highlight} faces.)
2425 Other packages might define their own faces; to see a list of all faces,
2426 use any of the interactive face-manipulation commands such as
2427 @code{set-face-font} and type @samp{?} when you are prompted for the
2430 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not
2431 specified in the resource database, then XEmacs attempts to derive them
2432 from the font of the default face. It can only succeed at this if you
2433 have specified the default font using the XLFD (X Logical Font
2434 Description) format, which looks like
2437 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2441 If you use any of the other, less strict font name formats, some of which
2445 lucidasanstypewriter-12
2450 then XEmacs won't be able to guess the names of the bold and italic
2451 versions. All X fonts can be referred to via XLFD-style names, so you
2452 should use those forms. See the man pages for @samp{X(1)},
2453 @samp{xlsfonts(1)}, and @samp{xfontsel(1)}.
2458 There are several structural widgets between the terminal EmacsFrame
2459 widget and the top level ApplicationShell; the exact names and types of
2460 these widgets change from release to release (for example, they changed
2461 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
2462 subject to further change in the future, so you should avoid mentioning
2463 them in your resource database. The above-mentioned syntaxes should be
2464 forward- compatible. As of 19.13, the exact widget hierarchy is as
2468 INVOCATION-NAME "shell" "container" FRAME-NAME
2469 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
2472 where INVOCATION-NAME is the terminal component of the name of the
2473 XEmacs executable (usually @samp{xemacs}), and
2474 @samp{x-emacs-application-class} is generally @samp{Emacs}.
2476 @node Menubar Resources
2477 @subsection Menubar Resources
2479 As the menubar is implemented as a widget which is not a part of XEmacs
2480 proper, it does not use the fac" mechanism for specifying fonts and
2481 colors: It uses whatever resources are appropriate to the type of widget
2482 which is used to implement it.
2484 If Emacs was compiled to use only the Motif-lookalike menu widgets, then one
2485 way to specify the font of the menubar would be
2488 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2491 If the Motif library is being used, then one would have to use
2494 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2497 because the Motif library uses the @code{fontList} resource name instead
2498 of @code{font}, which has subtly different semantics.
2500 The same is true of the scrollbars: They accept whichever resources are
2501 appropriate for the toolkit in use.