(U+9675): Use `->denotational' and `->subsumptive'.
[chise/xemacs-chise.git.1] / man / xemacs / custom.texi
1
2 @node Customization, Quitting, Emulation, Top
3 @chapter Customization
4 @cindex customization
5
6   This chapter talks about various topics relevant to adapting the
7 behavior of Emacs in minor ways.
8
9   All kinds of customization affect only the particular Emacs job that you
10 do them in.  They are completely lost when you kill the Emacs job, and
11 have no effect on other Emacs jobs you may run at the same time or
12 later.  The only way an Emacs job can affect anything outside of it is
13 by writing a file; in particular, the only way to make a customization
14 `permanent' is to put something in your init file or other appropriate
15 file to do the customization in each session.  @xref{Init File}.
16
17 @menu
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
28                      are parsed.
29 * Init File::       How to write common customizations in the init file.
30 * Audible Bell::    Changing how Emacs sounds the bell.
31 * Faces::           Changing the fonts and colors of a region of text.
32 * Frame Components::  Controlling the presence and positions of the
33                      menubar, toolbars, and gutters.
34 * X Resources::     X resources controlling various aspects of the
35                      behavior of XEmacs.
36 @end menu
37
38 @node Minor Modes
39 @section Minor Modes
40 @cindex minor modes
41
42 @cindex mode line
43   Minor modes are options which you can use or not.  For example, Auto
44 Fill mode is a minor mode in which @key{SPC} breaks lines between words
45 as you type.  All the minor modes are independent of each other and of
46 the selected major mode.  Most minor modes inform you in the mode line
47 when they are on; for example, @samp{Fill} in the mode line means that
48 Auto Fill mode is on.
49
50   Append @code{-mode} to the name of a minor mode to get the name of a
51 command function that turns the mode on or off.  Thus, the command to
52 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These
53 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
54 if you wish.  With no argument, the function turns the mode on if it was
55 off and off if it was on.  This is known as @dfn{toggling}.  A positive
56 argument always turns the mode on, and an explicit zero argument or a
57 negative argument always turns it off.
58
59 @cindex Auto Fill mode
60 @findex auto-fill-mode
61   Auto Fill mode allows you to enter filled text without breaking lines
62 explicitly.  Emacs inserts newlines as necessary to prevent lines from
63 becoming too long.  @xref{Filling}.
64
65 @cindex Overwrite mode
66 @findex overwrite-mode
67   Overwrite mode causes ordinary printing characters to replace existing
68 text instead of moving it to the right.  For example, if point is in
69 front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite
70 mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill
71
72 @cindex Abbrev mode
73 @findex abbrev-mode
74   Abbrev mode allows you to define abbreviations that automatically expand
75 as you type them.  For example, @samp{amd} might expand to @samp{abbrev
76 mode}.  @xref{Abbrevs}, for full information.
77
78 @node Variables
79 @section Variables
80 @cindex variable
81 @cindex option
82
83   A @dfn{variable} is a Lisp symbol which has a value.  Variable names
84 can contain any characters, but by convention they are words separated
85 by hyphens.  A variable can also have a documentation string, which
86 describes what kind of value it should have and how the value will be
87 used.
88
89   Lisp allows any variable to have any kind of value, but most variables
90 that Emacs uses require a value of a certain type.  Often the value has
91 to be a string or a number.  Sometimes we say that a certain feature is
92 turned on if a variable is ``non-@code{nil},'' meaning that if the
93 variable's value is @code{nil}, the feature is off, but the feature is
94 on for @i{any} other value.  The conventional value to turn on the
95 feature---since you have to pick one particular value when you set the
96 variable---is @code{t}.
97
98   Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
99 program must, but the most interesting variables for you are the ones that
100 exist for the sake of customization.  Emacs does not (usually) change the
101 values of these variables; instead, you set the values, and thereby alter
102 and control the behavior of certain Emacs commands.  These variables are
103 called @dfn{options}.  Most options are documented in this manual and
104 appear in the Variable Index (@pxref{Variable Index}).
105
106   One example of a variable which is an option is @code{fill-column}, which
107 specifies the position of the right margin (as a number of characters from
108 the left margin) to be used by the fill commands (@pxref{Filling}).
109
110 @menu
111 * Examining::           Examining or setting one variable's value.
112 * Easy Customization::  Convenient and easy customization of variables.
113 * Edit Options::        Examining or editing list of all variables' values.
114 * Locals::              Per-buffer values of variables.
115 * File Variables::      How files can specify variable values.
116 @end menu
117
118 @node Examining
119 @subsection Examining and Setting Variables
120 @cindex setting variables
121
122 @table @kbd
123 @item C-h v
124 @itemx M-x describe-variable
125 Print the value and documentation of a variable.
126 @findex set-variable
127 @item M-x set-variable
128 Change the value of a variable.
129 @end table
130
131 @kindex C-h v
132 @findex describe-variable
133   To examine the value of a single variable, use @kbd{C-h v}
134 (@code{describe-variable}), which reads a variable name using the
135 minibuffer, with completion.  It prints both the value and the
136 documentation of the variable.
137
138 @example
139 C-h v fill-column @key{RET}
140 @end example
141
142 @noindent
143 prints something like:
144
145 @smallexample
146 fill-column's value is 75
147
148 Documentation:
149 *Column beyond which automatic line-wrapping should happen.
150 Automatically becomes local when set in any fashion.
151 @end smallexample
152
153 @cindex option
154 @noindent
155 The star at the beginning of the documentation indicates that this variable
156 is an option.  @kbd{C-h v} is not restricted to options; it allows any
157 variable name.
158
159 @findex set-variable
160   If you know which option you want to set, you can use @kbd{M-x
161 set-variable} to set it.  This prompts for the variable name in the
162 minibuffer (with completion), and then prompts for a Lisp expression for the
163 new value using the minibuffer a second time.  For example,
164
165 @example
166 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
167 @end example
168
169 @noindent
170 sets @code{fill-column} to 75, as if you had executed the Lisp expression
171 @code{(setq fill-column 75)}.
172
173   Setting variables in this way, like all means of customizing Emacs
174 except where explicitly stated, affects only the current Emacs session.
175
176 @node Easy Customization
177 @subsection Easy Customization Interface
178
179 @findex customize
180 @cindex customization buffer
181   A convenient way to find the user option variables that you want to
182 change, and then change them, is with @kbd{M-x customize} (or use a
183 keyboard shortcut, @kbd{C-h C}.  This command
184 creates a @dfn{customization buffer} with which you can browse through
185 the Emacs user options in a logically organized structure, then edit and
186 set their values.  You can also use the customization buffer to save
187 settings permanently.  (Not all Emacs user options are included in this
188 structure as of yet, but we are adding the rest.)
189
190 @menu
191 * Groups: Customization Groups.
192                              How options are classified in a structure.
193 * Changing an Option::       How to edit a value and set an option.
194 * Face Customization::       How to edit the attributes of a face.
195 * Specific Customization::   Making a customization buffer for specific
196                                 options, faces, or groups.
197 @end menu
198
199 @node Customization Groups
200 @subsubsection Customization Groups
201 @cindex customization groups
202
203   For customization purposes, user options are organized into
204 @dfn{groups} to help you find them.  Groups are collected into bigger
205 groups, all the way up to a master group called @code{Emacs}.
206
207   @kbd{M-x customize} (or @kbd{C-h C}) creates a customization buffer that
208 shows the top-level @code{Emacs} group and the second-level groups immediately
209 under it.  It looks like this, in part:
210
211 @smallexample
212 /- Emacs group: ---------------------------------------------------\
213       [State]: visible group members are all at standard settings.
214    Customization of the One True Editor.
215    See also [Manual].
216
217  [Open] Editing group
218 Basic text editing facilities.
219
220  [Open] External group
221 Interfacing to external utilities.
222
223 @var{more second-level groups}
224
225 \- Emacs group end ------------------------------------------------/
226
227 @end smallexample
228
229 @noindent
230 This says that the buffer displays the contents of the @code{Emacs}
231 group.  The other groups are listed because they are its contents.  But
232 they are listed differently, without indentation and dashes, because
233 @emph{their} contents are not included.  Each group has a single-line
234 documentation string; the @code{Emacs} group also has a @samp{[State]}
235 line.
236
237 @cindex editable fields (customization buffer)
238 @cindex active fields (customization buffer)
239   Most of the text in the customization buffer is read-only, but it
240 typically includes some @dfn{editable fields} that you can edit.  There
241 are also @dfn{active fields}; this means a field that does something
242 when you @dfn{invoke} it.  To invoke an active field, either click on it
243 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
244
245   For example, the phrase @samp{[Open]} that appears in a second-level
246 group is an active field.  Invoking the @samp{[Open]} field for a group
247 opens up a new customization buffer, which shows that group and its
248 contents.  This field is a kind of hypertext link to another group.
249
250   The @code{Emacs} group does not include any user options itself, but
251 other groups do.  By examining various groups, you will eventually find
252 the options and faces that belong to the feature you are interested in
253 customizing.  Then you can use the customization buffer to set them.
254
255 @findex customize-browse
256   You can view the structure of customization groups on a larger scale
257 with @kbd{M-x customize-browse}.  This command creates a special kind of
258 customization buffer which shows only the names of the groups (and
259 options and faces), and their structure.
260
261   In this buffer, you can show the contents of a group by invoking
262 @samp{[+]}.  When the group contents are visible, this button changes to
263 @samp{[-]}; invoking that hides the group contents.
264
265   Each group, option or face name in this buffer has an active field
266 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}.  Invoking
267 that active field creates an ordinary customization buffer showing just
268 that group and its contents, just that option, or just that face.
269 This is the way to set values in it.
270
271 @node Changing an Option
272 @subsubsection Changing an Option
273
274   Here is an example of what a user option looks like in the
275 customization buffer:
276
277 @smallexample
278 Kill Ring Max: [Hide] 30
279    [State]: this option is unchanged from its standard setting.
280 Maximum length of kill ring before oldest elements are thrown away.
281 @end smallexample
282
283   The text following @samp{[Hide]}, @samp{30} in this case, indicates
284 the current value of the option.  If you see @samp{[Show]} instead of
285 @samp{[Hide]}, it means that the value is hidden; the customization
286 buffer initially hides values that take up several lines.  Invoke
287 @samp{[Show]} to show the value.
288
289   The line after the option name indicates the @dfn{customization state}
290 of the option: in the example above, it says you have not changed the
291 option yet.  The word @samp{[State]} at the beginning of this line is
292 active; you can get a menu of various operations by invoking it with
293 @kbd{Mouse-1} or @key{RET}.  These operations are essential for
294 customizing the variable.
295
296   The line after the @samp{[State]} line displays the beginning of the
297 option's documentation string.  If there are more lines of
298 documentation, this line ends with @samp{[More]}; invoke this to show
299 the full documentation string.
300
301   To enter a new value for @samp{Kill Ring Max}, move point to the value
302 and edit it textually.  For example, you can type @kbd{M-d}, then insert
303 another number.
304
305   When you begin to alter the text, you will see the @samp{[State]} line
306 change to say that you have edited the value:
307
308 @smallexample
309 [State]: you have edited the value as text, but not set the option.
310 @end smallexample
311
312 @cindex setting option value
313   Editing the value does not actually set the option variable.  To do
314 that, you must @dfn{set} the option.  To do this, invoke the word
315 @samp{[State]} and choose @samp{Set for Current Session}.
316
317   The state of the option changes visibly when you set it:
318
319 @smallexample
320 [State]: you have set this option, but not saved it for future sessions.
321 @end smallexample
322
323    You don't have to worry about specifying a value that is not valid;
324 setting the option checks for validity and will not really install an
325 unacceptable value.
326
327 @kindex M-TAB @r{(customization buffer)}
328 @findex widget-complete
329   While editing a value or field that is a file name, directory name,
330 command name, or anything else for which completion is defined, you can
331 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
332
333   Some options have a small fixed set of possible legitimate values.
334 These options don't let you edit the value textually.  Instead, an
335 active field @samp{[Value Menu]} appears before the value; invoke this
336 field to edit the value.  For a boolean ``on or off'' value, the active
337 field says @samp{[Toggle]}, and it changes to the other value.
338 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
339 take effect when you use the @samp{Set for Current Session} operation.
340
341   Some options have values with complex structure.  For example, the
342 value of @code{load-path} is a list of directories.  Here is how it
343 appears in the customization buffer:
344
345 @smallexample
346 Load Path:
347 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
348 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
349 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
350 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
351 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
352 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
353 [INS]
354    [State]: this item has been changed outside the customization buffer.
355 List of directories to search for files to load....
356 @end smallexample
357
358 @noindent
359 Each directory in the list appears on a separate line, and each line has
360 several editable or active fields.
361
362   You can edit any of the directory names.  To delete a directory from
363 the list, invoke @samp{[DEL]} on that line.  To insert a new directory in
364 the list, invoke @samp{[INS]} at the point where you want to insert it.
365
366   You can also invoke @samp{[Current dir?]} to switch between including
367 a specific named directory in the path, and including @code{nil} in the
368 path.  (@code{nil} in a search path means ``try the current
369 directory.'')
370
371 @kindex TAB @r{(customization buffer)}
372 @kindex S-TAB @r{(customization buffer)}
373 @findex widget-forward
374 @findex widget-backward
375   Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
376 moving through the customization buffer.  @key{TAB}
377 (@code{widget-forward}) moves forward to the next active or editable
378 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
379 previous active or editable field.
380
381   Typing @key{RET} on an editable field also moves forward, just like
382 @key{TAB}.  The reason for this is that people have a tendency to type
383 @key{RET} when they are finished editing a field.  If you have occasion
384 to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
385 C-j},
386
387 @cindex saving option value
388   Setting the option changes its value in the current Emacs session;
389 @dfn{saving} the value changes it for future sessions as well.  This
390 works by writing code into your init file so as to set the option
391 variable again each time you start Emacs.  @xref{Init File}.  To save
392 the option, invoke @samp{[State]} and select the @samp{Save for Future
393 Sessions} operation.
394
395   You can also restore the option to its standard value by invoking
396 @samp{[State]} and selecting the @samp{Reset} operation.  There are
397 actually three reset operations:
398
399 @table @samp
400 @item Reset to Current
401 If you have made some modifications and not yet set the option,
402 this restores the text in the customization buffer to match
403 the actual value.
404
405 @item Reset to Saved
406 This restores the value of the option to the last saved value,
407 and updates the text accordingly.
408
409 @item Reset to Standard Settings
410 This sets the option to its standard value, and updates the text
411 accordingly.  This also eliminates any saved value for the option,
412 so that you will get the standard value in future Emacs sessions.
413 @end table
414
415   The state of a group indicates whether anything in that group has been
416 edited, set or saved.  You can select @samp{Set for Current Session},
417 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
418 operation for the group; these operations on the group apply to all
419 options in the group and its subgroups.
420
421   Near the top of the customization buffer there are two lines
422 containing several active fields:
423
424 @smallexample
425  [Set] [Save] [Reset]  [Done]
426 @end smallexample
427
428 @noindent
429 Invoking @samp{[Done]} buries this customization buffer.  Each of the
430 other fields performs an operation---set, save or reset---on each of the
431 items in the buffer that could meaningfully be set, saved or reset.
432
433 @node Face Customization
434 @subsubsection Customizing Faces
435 @cindex customizing faces
436 @cindex bold font
437 @cindex italic font
438 @cindex fonts and faces
439
440   In addition to user options, some customization groups also include
441 faces.  When you show the contents of a group, both the user options and
442 the faces in the group appear in the customization buffer.  Here is an
443 example of how a face looks:
444
445 @smallexample
446 Custom Changed Face: (sample)
447    [State]: this face is unchanged from its standard setting.
448 Face used when the customize item has been changed.
449 Parent groups: [Custom Magic Faces]
450 Attributes: [ ] Bold: [Toggle]  off (nil)
451             [ ] Italic: [Toggle]  off (nil)
452             [ ] Underline: [Toggle]  off (nil)
453             [ ] Foreground: white       (sample)
454             [ ] Background: blue        (sample)
455             [ ] Inverse: [Toggle]  off (nil)
456             [ ] Stipple: 
457             [ ] Font Family: 
458             [ ] Size: 
459             [ ] Strikethru: off
460 @end smallexample
461
462   Each face attribute has its own line.  The @samp{[@var{x}]} field
463 before the attribute name indicates whether the attribute is
464 @dfn{enabled}; @samp{X} means that it is.  You can enable or disable the
465 attribute by invoking that field.  When the attribute is enabled, you
466 can change the attribute value in the usual ways.
467
468 @xref{Faces}, for description of how @code{face-frob-from-locale-first}
469 variable affects changing @samp{Bold} and @samp{Italic} attributes.
470
471 @c Is this true for XEmacs?
472 @c  On a black-and-white display, the colors you can use for the
473 @c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
474 @c and @samp{gray3}.  Emacs supports these shades of gray by using
475 @c background stipple patterns instead of a color.
476 @c 
477   Setting, saving and resetting a face work like the same operations for
478 options (@pxref{Changing an Option}).
479
480   A face can specify different appearances for different types of
481 display.  For example, a face can make text red on a color display, but
482 use a bold font on a monochrome display.  To specify multiple
483 appearances for a face, select @samp{Show Display Types} in the menu you
484 get from invoking @samp{[State]}.
485
486 @c It would be cool to implement this
487 @c @findex modify-face
488 @c   Another more basic way to set the attributes of a specific face is
489 @c with @kbd{M-x modify-face}.  This command reads the name of a face, then
490 @c reads the attributes one by one.  For the color and stipple attributes,
491 @c the attribute's current value is the default---type just @key{RET} if
492 @c you don't want to change that attribute.  Type @samp{none} if you want
493 @c to clear out the attribute.
494
495 @node Specific Customization
496 @subsubsection Customizing Specific Items
497
498   Instead of finding the options you want to change by moving down
499 through the structure of groups, you can specify the particular option,
500 face or group that you want to customize.
501
502 @table @kbd
503 @item M-x customize-option @key{RET} @var{option} @key{RET}
504 Set up a customization buffer with just one option, @var{option}.
505 @item M-x customize-face @key{RET} @var{face} @key{RET}
506 Set up a customization buffer with just one face, @var{face}.
507 @item M-x customize-group @key{RET} @var{group} @key{RET}
508 Set up a customization buffer with just one group, @var{group}.
509 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
510 Set up a customization buffer with all the options, faces and groups
511 that match @var{regexp}.
512 @item M-x customize-saved 
513 Set up a customization buffer containing all options and faces that you
514 have saved with customization buffers.
515 @item M-x customize-customized
516 Set up a customization buffer containing all options and faces that you
517 have customized but not saved.
518 @end table
519
520 @findex customize-option
521   If you want to alter a particular user option variable with the
522 customization buffer, and you know its name, you can use the command
523 @kbd{M-x customize-option} and specify the option name.  This sets up
524 the customization buffer with just one option---the one that you asked
525 for.  Editing, setting and saving the value work as described above, but
526 only for the specified option.
527
528 @findex customize-face
529   Likewise, you can modify a specific face, chosen by name, using
530 @kbd{M-x customize-face}.
531
532 @findex customize-group
533   You can also set up the customization buffer with a specific group,
534 using @kbd{M-x customize-group}.  The immediate contents of the chosen
535 group, including option variables, faces, and other groups, all appear
536 as well.  However, these subgroups' own contents start out hidden.  You
537 can show their contents in the usual way, by invoking @samp{[Show]}.
538
539 @findex customize-apropos
540   To control more precisely what to customize, you can use @kbd{M-x
541 customize-apropos}.  You specify a regular expression as argument; then
542 all options, faces and groups whose names match this regular expression
543 are set up in the customization buffer.  If you specify an empty regular
544 expression, this includes @emph{all} groups, options and faces in the
545 customization buffer (but that takes a long time).
546
547 @findex customize-saved
548 @findex customize-customized
549   If you change option values and then decide the change was a mistake,
550 you can use two special commands to revisit your previous changes.  Use
551 @kbd{customize-saved} to look at the options and faces that you have
552 saved.  Use @kbd{M-x customize-customized} to look at the options and
553 faces that you have set but not saved.
554
555 @node Edit Options
556 @subsection Editing Variable Values
557
558 @table @kbd
559 @item M-x list-options
560 Display a buffer listing names, values, and documentation of all options.
561 @item M-x edit-options
562 Change option values by editing a list of options.
563 @end table
564
565 @findex list-options
566   @kbd{M-x list-options} displays a list of all Emacs option variables in
567 an Emacs buffer named @samp{*List Options*}.  Each option is shown with its
568 documentation and its current value.  Here is what a portion of it might
569 look like:
570
571 @smallexample
572 ;; exec-path:
573 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
574 *List of directories to search programs to run in subprocesses.
575 Each element is a string (directory name)
576 or nil (try the default directory).
577 ;;
578 ;; fill-column:
579 75
580 *Column beyond which automatic line-wrapping should happen.
581 Automatically becomes local when set in any fashion.
582 ;;
583 @end smallexample
584
585 @findex edit-options
586   @kbd{M-x edit-options} goes one step further and immediately selects the
587 @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
588 which provides commands that allow you to point at an option and change its
589 value:
590
591 @table @kbd
592 @item s
593 Set the variable point is in or near to a new value read using the
594 minibuffer.
595 @item x
596 Toggle the variable point is in or near: if the value was @code{nil},
597 it becomes @code{t}; otherwise it becomes @code{nil}.
598 @item 1
599 Set the variable point is in or near to @code{t}.
600 @item 0
601 Set the variable point is in or near to @code{nil}.
602 @item n
603 @itemx p
604 Move to the next or previous variable.
605 @end table
606
607 @node Locals
608 @subsection Local Variables
609
610 @table @kbd
611 @item M-x make-local-variable
612 Make a variable have a local value in the current buffer.
613 @item M-x kill-local-variable
614 Make a variable use its global value in the current buffer.
615 @item M-x make-variable-buffer-local
616 Mark a variable so that setting it will make it local to the
617 buffer that is current at that time.
618 @end table
619
620 @cindex local variables
621    You can make any variable @dfn{local} to a specific Emacs buffer.
622 This means that the variable's value in that buffer is independent of
623 its value in other buffers.  A few variables are always local in every
624 buffer.  All other Emacs variables have a @dfn{global} value which is in
625 effect in all buffers that have not made the variable local.
626
627   Major modes always make the variables they set local to the buffer.
628 This is why changing major modes in one buffer has no effect on other
629 buffers.
630
631 @findex make-local-variable
632   @kbd{M-x make-local-variable} reads the name of a variable and makes it
633 local to the current buffer.  Further changes in this buffer will not
634 affect others, and changes in the global value will not affect this
635 buffer.
636
637 @findex make-variable-buffer-local
638 @cindex per-buffer variables
639   @kbd{M-x make-variable-buffer-local} reads the name of a variable and
640 changes the future behavior of the variable so that it automatically
641 becomes local when it is set.  More precisely, once you have marked a
642 variable in this way, the usual ways of setting the
643 variable will automatically invoke @code{make-local-variable} first.  We
644 call such variables @dfn{per-buffer} variables.
645
646   Some important variables have been marked per-buffer already.  They
647 include @code{abbrev-mode}, @code{auto-fill-function},
648 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
649 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
650 @code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode},
651 @code{selective-display-ellipses}, @*@code{selective-display},
652 @code{tab-width}, and @code{truncate-lines}.  Some other variables are
653 always local in every buffer, but they are used for internal
654 purposes.@refill
655
656 Note: the variable @code{auto-fill-function} was formerly named
657 @code{auto-fill-hook}.
658
659 @findex kill-local-variable
660   If you want a variable to cease to be local to the current buffer,
661 call @kbd{M-x kill-local-variable} and provide the name of a variable to
662 the prompt.  The global value of the variable
663 is again in effect in this buffer.  Setting the major mode kills all
664 the local variables of the buffer.
665
666 @findex setq-default
667   To set the global value of a variable, regardless of whether the
668 variable has a local value in the current buffer, you can use the
669 Lisp function @code{setq-default}.  It works like @code{setq}.
670 If there is a local value in the current buffer, the local value is
671 not affected by @code{setq-default}; thus, the new global value may
672 not be visible until you switch to another buffer, as in the case of:
673
674 @example
675 (setq-default fill-column 75)
676 @end example
677
678 @noindent
679 @code{setq-default} is the only way to set the global value of a variable
680 that has been marked with @code{make-variable-buffer-local}.
681
682 @findex default-value
683   Programs can look at a variable's default value with @code{default-value}.
684 This function takes a symbol as an argument and returns its default value.
685 The argument is evaluated; usually you must quote it explicitly, as in
686 the case of:
687
688 @example
689 (default-value 'fill-column)
690 @end example
691
692 @node File Variables
693 @subsection Local Variables in Files
694 @cindex local variables in files
695
696   A file can contain a @dfn{local variables list}, which specifies the
697 values to use for certain Emacs variables when that file is edited.
698 Visiting the file checks for a local variables list and makes each variable
699 in the list local to the buffer in which the file is visited, with the
700 value specified in the file.
701
702   A local variables list goes near the end of the file, in the last page.
703 (It is often best to put it on a page by itself.)  The local variables list
704 starts with a line containing the string @samp{Local Variables:}, and ends
705 with a line containing the string @samp{End:}.  In between come the
706 variable names and values, one set per line, as @samp{@var{variable}:@:
707 @var{value}}.  The @var{value}s are not evaluated; they are used literally.
708
709   The line which starts the local variables list does not have to say
710 just @samp{Local Variables:}.  If there is other text before @samp{Local
711 Variables:}, that text is called the @dfn{prefix}, and if there is other
712 text after, that is called the @dfn{suffix}.  If a prefix or suffix are
713 present, each entry in the local variables list should have the prefix
714 before it and the suffix after it.  This includes the @samp{End:} line.
715 The prefix and suffix are included to disguise the local variables list
716 as a comment so the compiler or text formatter  will ignore it.
717 If you do not need to disguise the local variables list as a comment in
718 this way, there is no need to include a prefix or a suffix.@refill
719
720   Two ``variable'' names are special in a local variables list: a value
721 for the variable @code{mode} sets the major mode, and a value for the
722 variable @code{eval} is simply evaluated as an expression and the value
723 is ignored.  These are not real variables; setting them in any other
724 context does not have the same effect.  If @code{mode} is used in a
725 local variables list, it should be the first entry in the list.
726
727 Here is an example of a local variables list:
728 @example
729 ;;; Local Variables: ***
730 ;;; mode:lisp ***
731 ;;; comment-column:0 ***
732 ;;; comment-start: ";;; "  ***
733 ;;; comment-end:"***" ***
734 ;;; End: ***
735 @end example
736
737   Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.
738 Note also that comments in the file begin with and end with the same
739 strings.  Presumably the file contains code in a language which is
740 enough like Lisp for Lisp mode to be useful but in which comments
741 start and end differently.  The prefix and suffix are used in the local
742 variables list to make the list look like several lines of comments when
743 the compiler or interpreter for that language reads the file. 
744
745   The start of the local variables list must be no more than 3000
746 characters from the end of the file, and must be in the last page if the
747 file is divided into pages.  Otherwise, Emacs will not notice it is
748 there.  The purpose is twofold: a stray @samp{Local Variables:}@: not in
749 the last page does not confuse Emacs, and Emacs never needs to search a
750 long file that contains no page markers and has no local variables list.
751
752   You may be tempted to turn on Auto Fill mode with a local variable
753 list.  That is inappropriate.  Whether you use Auto Fill mode or not is
754 a matter of personal taste, not a matter of the contents of particular
755 files.  If you want to use Auto Fill, set up major mode hooks with your
756 init file to turn it on (when appropriate) for you alone
757 (@pxref{Init File}).  Don't try to use a local variable list that would
758 impose your taste on everyone working with the file.
759
760 XEmacs allows you to specify local variables in the first line
761 of a file, in addition to specifying them in the @code{Local Variables}
762 section at the end of a file.
763
764 If the first line of a file contains two occurrences of @code{`-*-'},
765 XEmacs uses the information between them to determine what the major
766 mode and variable settings should be.  For example, these are all legal:
767
768 @example
769         ;;; -*- mode: emacs-lisp -*-
770         ;;; -*- mode: postscript; version-control: never -*-
771         ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
772 @end example
773
774 For historical reasons, the syntax @code{`-*- modename -*-'} is allowed
775 as well; for example, you can use:
776
777 @example
778         ;;; -*- emacs-lisp -*-
779 @end example
780
781 @vindex enable-local-variables
782 The variable @code{enable-local-variables} controls the use of local
783 variables lists in files you visit.  The value can be @code{t},
784 @code{nil}, or something else.  A value of @code{t} means local variables
785 lists are obeyed; @code{nil} means they are ignored; anything else means
786 query.
787
788 The command @code{M-x normal-mode} always obeys local variables lists
789 and ignores this variable.
790
791 @node Keyboard Macros
792 @section Keyboard Macros
793
794 @cindex keyboard macros
795   A @dfn{keyboard macro} is a command defined by the user to abbreviate a
796 sequence of keys.  For example, if you discover that you are about to type
797 @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
798 macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty.
799
800 @c widecommands
801 @table @kbd
802 @item C-x (
803 Start defining a keyboard macro (@code{start-kbd-macro}).
804 @item C-x )
805 End the definition of a keyboard macro (@code{end-kbd-macro}).
806 @item C-x e
807 Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
808 @item C-u C-x (
809 Re-execute last keyboard macro, then add more keys to its definition.
810 @item C-x q
811 When this point is reached during macro execution, ask for confirmation
812 (@code{kbd-macro-query}).
813 @item M-x name-last-kbd-macro
814 Give a command name (for the duration of the session) to the most
815 recently defined keyboard macro.
816 @item M-x insert-kbd-macro
817 Insert in the buffer a keyboard macro's definition, as Lisp code.
818 @end table
819
820   Keyboard macros differ from other Emacs commands in that they are
821 written in the Emacs command language rather than in Lisp.  This makes it
822 easier for the novice to write them and makes them more convenient as
823 temporary hacks.  However, the Emacs command language is not powerful
824 enough as a programming language to be useful for writing anything
825 general or complex.  For such things, Lisp must be used.
826
827   You define a keyboard macro by executing the commands which are its
828 definition.  Put differently, as you are defining a keyboard macro, the
829 definition is being executed for the first time.  This way, you see
830 what the effects of your commands are, and don't have to figure
831 them out in your head.  When you are finished, the keyboard macro is
832 defined and also has been executed once.  You can then execute the same
833 set of commands again by invoking the macro.
834
835 @menu
836 * Basic Kbd Macro::     Defining and running keyboard macros.
837 * Save Kbd Macro::      Giving keyboard macros names; saving them in files.
838 * Kbd Macro Query::     Keyboard macros that do different things each use.
839 @end menu
840
841 @node Basic Kbd Macro
842 @subsection Basic Use
843
844 @kindex C-x (
845 @kindex C-x )
846 @kindex C-x e
847 @findex start-kbd-macro
848 @findex end-kbd-macro
849 @findex call-last-kbd-macro
850   To start defining a keyboard macro, type @kbd{C-x (}
851 (@code{start-kbd-macro}).  From then on, anything you type continues to be
852 executed, but also becomes part of the definition of the macro.  @samp{Def}
853 appears in the mode line to remind you of what is going on.  When you are
854 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
855 definition, without becoming part of it. 
856
857   For example,
858
859 @example
860 C-x ( M-f foo C-x )
861 @end example
862
863 @noindent
864 defines a macro to move forward a word and then insert @samp{foo}.
865
866 You can give @kbd{C-x )} a repeat count as an argument, in which case it
867 repeats the macro that many times right after defining it, but defining
868 the macro counts as the first repetition (since it is executed as you
869 define it).  If you give @kbd{C-x )} an argument of 4, it executes the
870 macro immediately 3 additional times.  An argument of zero to @kbd{C-x
871 e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an
872 error or you type @kbd{C-g}).
873
874   Once you have defined a macro, you can invoke it again with the
875 @kbd{C-x e} command (@code{call-last-kbd-macro}).  You can give the
876 command a repeat count numeric argument to execute the macro many times.
877
878   To repeat an operation at regularly spaced places in the
879 text, define a macro and include as part of the macro the commands to move
880 to the next place you want to use it.  For example, if you want to change
881 each line, you should position point at the start of a line, and define a
882 macro to change that line and leave point at the start of the next line.
883 Repeating the macro will then operate on successive lines.
884
885   After you have terminated the definition of a keyboard macro, you can add
886 to the end of its definition by typing @kbd{C-u C-x (}.  This is equivalent
887 to plain @kbd{C-x (} followed by retyping the whole definition so far.  As
888 a consequence it re-executes the macro as previously defined.
889
890 @node Save Kbd Macro
891 @subsection Naming and Saving Keyboard Macros
892
893 @findex name-last-kbd-macro
894   To save a keyboard macro for longer than until you define the
895 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
896 This reads a name as an argument using the minibuffer and defines that name
897 to execute the macro.  The macro name is a Lisp symbol, and defining it in
898 this way makes it a valid command name for calling with @kbd{M-x} or for
899 binding a key to with @code{global-set-key} (@pxref{Keymaps}).  If you
900 specify a name that has a prior definition other than another keyboard
901 macro, Emacs prints an error message and nothing is changed.
902
903 @findex insert-kbd-macro
904   Once a macro has a command name, you can save its definition in a file.
905 You can then use it in another editing session.  First visit the file
906 you want to save the definition in.  Then use the command:
907
908 @example
909 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
910 @end example
911
912 @noindent
913 This inserts some Lisp code that, when executed later, will define the same
914 macro with the same definition it has now.  You need not understand Lisp
915 code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
916 Then save the file.  You can load the file with @code{load-file}
917 (@pxref{Lisp Libraries}).  If the file you save in is your initialization file
918 (@pxref{Init File}), then the macro will be defined each
919 time you run Emacs.
920
921   If you give @code{insert-kbd-macro} a prefix argument, it creates
922 additional Lisp code to record the keys (if any) that you have bound to the
923 keyboard macro, so that the macro is reassigned the same keys when you
924 load the file.
925
926 @node Kbd Macro Query
927 @subsection Executing Macros With Variations
928
929 @kindex C-x q
930 @findex kbd-macro-query
931   You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar
932 to that of @code{query-replace}.  The macro asks you  each time
933 whether to make a change.  When you are defining the macro, type @kbd{C-x
934 q} at the point where you want the query to occur.  During macro
935 definition, the @kbd{C-x q} does nothing, but when you invoke the macro,
936 @kbd{C-x q} reads a character from the terminal to decide whether to
937 continue.
938
939   The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL},
940 @kbd{C-d}, @kbd{C-l}, and @kbd{C-r}.  Any other character terminates
941 execution of the keyboard macro and is then read as a command.
942 @key{SPC} means to continue.  @key{DEL} means to skip the remainder of
943 this repetition of the macro, starting again from the beginning in the
944 next repetition.  @kbd{C-d} means to skip the remainder of this
945 repetition and cancel further repetition.  @kbd{C-l} redraws the frame
946 and asks you again for a character to specify what to do.  @kbd{C-r} enters
947 a recursive editing level, in which you can perform editing that is not
948 part of the macro.  When you exit the recursive edit using @kbd{C-M-c},
949 you are asked again how to continue with the keyboard macro.  If you
950 type a @key{SPC} at this time, the rest of the macro definition is
951 executed.  It is up to you to leave point and the text in a state such
952 that the rest of the macro will do what you want.@refill
953
954   @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
955 different function.  It enters a recursive edit reading input from the
956 keyboard, both when you type it during the definition of the macro and
957 when it is executed from the macro.  During definition, the editing you do
958 inside the recursive edit does not become part of the macro.  During macro
959 execution, the recursive edit gives you a chance to do some particularized
960 editing.  @xref{Recursive Edit}.
961
962 @node Key Bindings
963 @section Customizing Key Bindings
964
965   This section deals with the @dfn{keymaps} that define the bindings
966 between keys and functions, and shows how you can customize these bindings.
967 @cindex command
968 @cindex function
969 @cindex command name
970
971   A command is a Lisp function whose definition provides for interactive
972 use.  Like every Lisp function, a command has a function name, which is
973 a Lisp symbol whose name usually consists of lower case letters and
974 hyphens.
975
976 @menu
977 * Keymaps::    Definition of the keymap data structure.
978                Names of Emacs's standard keymaps.
979 * Rebinding::  How to redefine one key's meaning conveniently.
980 * Disabling::  Disabling a command means confirmation is required
981                 before it can be executed.  This is done to protect
982                 beginners from surprises.
983 @end menu
984
985 @node Keymaps
986 @subsection Keymaps
987 @cindex keymap
988
989 @cindex global keymap
990 @vindex global-map
991   The bindings between characters and command functions are recorded in
992 data structures called @dfn{keymaps}.  Emacs has many of these.  One, the
993 @dfn{global} keymap, defines the meanings of the single-character keys that
994 are defined regardless of major mode.  It is the value of the variable
995 @code{global-map}.
996
997 @cindex local keymap
998 @vindex c-mode-map
999 @vindex lisp-mode-map
1000   Each major mode has another keymap, its @dfn{local keymap}, which
1001 contains overriding definitions for the single-character keys that are
1002 redefined in that mode.  Each buffer records which local keymap is
1003 installed for it at any time, and the current buffer's local keymap is
1004 the only one that directly affects command execution.  The local keymaps
1005 for Lisp mode, C mode, and many other major modes always exist even when
1006 not in use.  They are the values of the variables @code{lisp-mode-map},
1007 @code{c-mode-map}, and so on.  For less frequently used major modes, the
1008 local keymap is sometimes constructed only when the mode is used for the
1009 first time in a session, to save space.
1010
1011 @cindex minibuffer
1012 @vindex minibuffer-local-map
1013 @vindex minibuffer-local-ns-map
1014 @vindex minibuffer-local-completion-map
1015 @vindex minibuffer-local-must-match-map
1016 @vindex repeat-complex-command-map
1017 @vindex isearch-mode-map
1018   There are local keymaps for the minibuffer, too; they contain various
1019 completion and exit commands.
1020
1021 @itemize @bullet
1022 @item
1023 @code{minibuffer-local-map} is used for ordinary input (no completion).
1024 @item
1025 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1026 just like @key{RET}.  This is used mainly for Mocklisp compatibility.
1027 @item
1028 @code{minibuffer-local-completion-map} is for permissive completion.
1029 @item
1030 @code{minibuffer-local-must-match-map} is for strict completion and
1031 for cautious completion.
1032 @item
1033 @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC} @key{ESC}}.
1034 @item
1035 @code{isearch-mode-map} contains the bindings of the special keys which
1036 are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}.
1037 @end itemize
1038
1039 @vindex ctl-x-map
1040 @vindex help-map
1041 @vindex esc-map
1042   Finally, each prefix key has a keymap which defines the key sequences
1043 that start with it.  For example, @code{ctl-x-map} is the keymap used for
1044 characters following a @kbd{C-x}.
1045
1046 @itemize @bullet
1047 @item
1048 @code{ctl-x-map} is the variable name for the map used for characters that
1049 follow @kbd{C-x}.
1050 @item
1051 @code{help-map} is used for characters that follow @kbd{C-h}.
1052 @item
1053 @code{esc-map} is for characters that follow @key{ESC}. All Meta
1054 characters are actually defined by this map.
1055 @item
1056 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1057 @item
1058 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1059 @end itemize
1060
1061   The definition of a prefix key is the keymap to use for looking up
1062 the following character.  Sometimes the definition is actually a Lisp
1063 symbol whose function definition is the following character keymap.  The
1064 effect is the same, but it provides a command name for the prefix key that
1065 you can use as a description of what the prefix key is for.  Thus the
1066 binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
1067 definition is the keymap for @kbd{C-x} commands, the value of
1068 @code{ctl-x-map}.@refill
1069
1070   Prefix key definitions can appear in either the global
1071 map or a local map.  The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
1072 and @key{ESC} as prefix keys appear in the global map, so these prefix
1073 keys are always available.  Major modes can locally redefine a key as a
1074 prefix by putting a prefix key definition for it in the local
1075 map.@refill
1076
1077   A mode can also put a prefix definition of a global prefix character such
1078 as @kbd{C-x} into its local map.  This is how major modes override the
1079 definitions of certain keys that start with @kbd{C-x}.  This case is
1080 special, because the local definition does not entirely replace the global
1081 one.  When both the global and local definitions of a key are other
1082 keymaps, the next character is looked up in both keymaps, with the local
1083 definition overriding the global one.  The character after the
1084 @kbd{C-x} is looked up in both the major mode's own keymap for redefined
1085 @kbd{C-x} commands and in @code{ctl-x-map}.  If the major mode's own keymap
1086 for @kbd{C-x} commands contains @code{nil}, the definition from the global
1087 keymap for @kbd{C-x} commands is used.@refill
1088
1089 @node Rebinding
1090 @subsection Changing Key Bindings
1091 @cindex key rebinding, this session
1092 @cindex rebinding keys, this session
1093
1094   You can redefine an Emacs key by changing its entry in a keymap.
1095 You can change the global keymap, in which case the change is effective in
1096 all major modes except those that have their own overriding local
1097 definitions for the same key.  Or you can change the current buffer's
1098 local map, which affects all buffers using the same major mode.
1099
1100 @menu
1101 * Interactive Rebinding::      Changing Key Bindings Interactively   
1102 * Programmatic Rebinding::     Changing Key Bindings Programmatically
1103 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings 
1104 @end menu
1105
1106 @node Interactive Rebinding
1107 @subsubsection Changing Key Bindings Interactively
1108 @findex global-set-key
1109 @findex local-set-key
1110 @findex local-unset-key
1111
1112 @table @kbd
1113 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1114 Defines @var{key} globally to run @var{cmd}.
1115 @item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET} 
1116 Defines @var{key} locally (in the major mode now in effect) to run
1117 @var{cmd}.
1118 @item M-x local-unset-key @key{RET} @var{keys} @key{RET}
1119 Removes the local binding of @var{key}.
1120 @end table
1121
1122 @var{cmd} is a symbol naming an interactively-callable function.
1123
1124 When called interactively, @var{key} is the next complete key sequence
1125 that you type.  When called as a function, @var{key} is a string, a
1126 vector of events, or a vector of key-description lists as described in
1127 the @code{define-key} function description.  The binding goes in
1128 the current buffer's local map, which is shared with other buffers in
1129 the same major mode.
1130
1131 The following example:
1132
1133 @example
1134 M-x global-set-key @key{RET} C-f next-line @key{RET}
1135 @end example
1136
1137 @noindent
1138 redefines @kbd{C-f} to move down a line.  The fact that @var{cmd} is
1139 read second makes it serve as a kind of confirmation for @var{key}.
1140
1141   These functions offer no way to specify a particular prefix keymap as
1142 the one to redefine in, but that is not necessary, as you can include
1143 prefixes in @var{key}.  @var{key} is read by reading characters one by
1144 one until they amount to a complete key (that is, not a prefix key).
1145 Thus, if you type @kbd{C-f} for @var{key}, Emacs enters
1146 the minibuffer immediately to read @var{cmd}.  But if you type
1147 @kbd{C-x}, another character is read; if that character is @kbd{4},
1148 another character is read, and so on.  For example,@refill
1149
1150 @example
1151 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1152 @end example
1153
1154 @noindent
1155 redefines @kbd{C-x 4 $} to run the (fictitious) command
1156 @code{spell-other-window}.
1157
1158 @findex define-key
1159 @findex substitute-key-definition
1160   The most general way to modify a keymap is the function
1161 @code{define-key}, used in Lisp code (such as your init file).
1162 @code{define-key} takes three arguments: the keymap, the key to modify
1163 in it, and the new definition.  @xref{Init File}, for an example.
1164 @code{substitute-key-definition} is used similarly; it takes three
1165 arguments, an old definition, a new definition, and a keymap, and
1166 redefines in that keymap all keys that were previously defined with the
1167 old definition to have the new definition instead.
1168
1169 @node Programmatic Rebinding
1170 @subsubsection Changing Key Bindings Programmatically
1171
1172   You can use the functions @code{global-set-key} and @code{define-key}
1173 to rebind keys under program control.
1174
1175 @findex define-key
1176 @findex global-set-key
1177
1178 @table @kbd
1179 @item  @code{(global-set-key @var{keys} @var{cmd})}
1180 Defines @var{keys} globally to run @var{cmd}.
1181 @item @code{(define-key @var{keymap} @var{keys} @var{def})}
1182 Defines @var{keys} to run @var{def} in the keymap @var{keymap}.
1183 @end table
1184  
1185 @var{keymap} is a keymap object.
1186
1187 @var{keys} is the sequence of keystrokes to bind.
1188
1189 @var{def} is anything that can be a key's definition:
1190
1191 @itemize @bullet
1192 @item
1193 @code{nil}, meaning key is undefined in this keymap
1194 @item
1195 A command, that is, a Lisp function suitable for interactive calling
1196 @item
1197 A string or key sequence vector, which is treated as a keyboard macro
1198 @item
1199 A keymap to define a prefix key
1200 @item
1201 A symbol so that when the key is looked up, the symbol stands for its
1202 function definition, which should at that time be one of the above,
1203 or another symbol whose function definition is used, and so on
1204 @item
1205 A cons, @code{(string . defn)}, meaning that @var{defn} is the definition
1206 (@var{defn} should be a valid definition in its own right)
1207 @item
1208 A cons, @code{(keymap . char)}, meaning use the definition of
1209 @var{char} in map @var{keymap}
1210 @end itemize
1211
1212 For backward compatibility, XEmacs allows you to specify key
1213 sequences as strings.  However, the preferred method is to use the
1214 representations of key sequences as vectors of keystrokes.
1215 @xref{Keystrokes}, for more information about the rules for constructing
1216 key sequences.
1217
1218 Emacs allows you to abbreviate representations for key sequences in 
1219 most places where there is no ambiguity.
1220 Here are some rules for abbreviation:
1221
1222 @itemize @bullet
1223 @item
1224 The keysym by itself is equivalent to a list of just that keysym, i.e.,
1225 @code{f1} is equivalent to @code{(f1)}.
1226 @item
1227 A keystroke by itself is equivalent to a vector containing just that
1228 keystroke, i.e.,  @code{(control a)} is equivalent to @code{[(control a)]}.
1229 @item
1230 You can use ASCII codes for keysyms that have them. i.e.,
1231 @code{65} is equivalent to @code{A}. (This is not so much an
1232 abbreviation as an alternate representation.)
1233 @end itemize
1234
1235 Here are some examples of programmatically binding keys:
1236
1237 @example
1238
1239 ;;;  Bind @code{my-command} to @key{f1}
1240 (global-set-key 'f1 'my-command)                
1241
1242 ;;;  Bind @code{my-command} to @kbd{Shift-f1}
1243 (global-set-key '(shift f1) 'my-command)
1244
1245 ;;; Bind @code{my-command} to @kbd{C-c Shift-f1}
1246 (global-set-key '[(control c) (shift f1)] 'my-command)  
1247
1248 ;;; Bind @code{my-command} to the middle mouse button.
1249 (global-set-key 'button2 'my-command)
1250
1251 ;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}}
1252 ;;; in the keymap that is in force when you are running @code{dired}.
1253 (define-key dired-mode-map '(meta control button3) 'my-command)
1254
1255 @end example
1256
1257 @comment ;; note that these next four lines are not synonymous:
1258 @comment ;;
1259 @comment (global-set-key '(meta control delete) 'my-command)
1260 @comment (global-set-key '(meta control backspace) 'my-command)
1261 @comment (global-set-key '(meta control h) 'my-command)
1262 @comment (global-set-key '(meta control H) 'my-command)
1263 @comment 
1264 @comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''.
1265 @comment ;;
1266 @comment (global-set-key "\^J" 'my-command)
1267
1268 @node Key Bindings Using Strings
1269 @subsubsection Using Strings for Changing Key Bindings 
1270
1271   For backward compatibility, you can still use strings to represent
1272 key sequences.  Thus you can use commands like the following:
1273
1274 @example
1275 ;;; Bind @code{end-of-line} to @kbd{C-f}
1276 (global-set-key "\C-f" 'end-of-line)
1277 @end example
1278
1279 Note, however, that in some cases you may be binding more than one
1280 key sequence by using a single command.  This situation can 
1281 arise because in ASCII, @kbd{C-i} and @key{TAB} have
1282 the same representation.  Therefore, when Emacs sees:
1283
1284 @example
1285 (global-set-key "\C-i" 'end-of-line)
1286 @end example
1287
1288 it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}.
1289 The solution XEmacs adopts is to bind both of these key
1290 sequences.
1291
1292 @cindex redefining keys
1293 After binding a command to two key sequences with a form like:
1294
1295 @example
1296         (define-key global-map "\^X\^I" 'command-1)
1297 @end example
1298
1299 it is possible to redefine only one of those sequences like so:
1300
1301 @example
1302         (define-key global-map [(control x) (control i)] 'command-2)
1303         (define-key global-map [(control x) tab] 'command-3)
1304 @end example
1305
1306 This applies only when running under a window system.  If you are
1307 talking to Emacs through an ASCII-only channel, you do not get any of
1308 these features.
1309
1310 Here is a table of pairs of key sequences that behave in a
1311 similar fashion:
1312
1313 @example
1314         control h      backspace           
1315         control l      clear
1316         control i      tab 
1317         control m      return              
1318         control j      linefeed 
1319         control [      escape
1320         control @@      control space
1321 @end example
1322
1323 @node Disabling
1324 @subsection Disabling Commands
1325 @cindex disabled command
1326
1327   Disabling a command marks it as requiring confirmation before it
1328 can be executed.  The purpose of disabling a command is to prevent
1329 beginning users from executing it by accident and being confused.
1330
1331   The direct mechanism for disabling a command is to have a non-@code{nil}
1332 @code{disabled} property on the Lisp symbol for the command.  These
1333 properties are normally set by the user's init file with
1334 Lisp expressions such as:
1335
1336 @example
1337 (put 'delete-region 'disabled t)
1338 @end example
1339
1340 @xref{Init File}.
1341
1342   If the value of the @code{disabled} property is a string, that string
1343 is included in the message printed when the command is used:
1344
1345 @example
1346 (put 'delete-region 'disabled
1347      "Text deleted this way cannot be yanked back!\n")
1348 @end example
1349
1350 @findex disable-command
1351 @findex enable-command
1352   You can disable a command either by editing the init file
1353 directly or with the command @kbd{M-x disable-command}, which edits the
1354 init file for you.  @xref{Init File}.
1355
1356   When you attempt to invoke a disabled command interactively in Emacs,
1357 a window is displayed containing the command's name, its
1358 documentation, and some instructions on what to do next; then
1359 Emacs asks for input saying whether to execute the command as requested,
1360 enable it and execute, or cancel it.  If you decide to enable the
1361 command, you are asked whether to do this permanently or just for the
1362 current session.  Enabling permanently works by automatically editing
1363 your init file.  You can use @kbd{M-x enable-command} at any
1364 time to enable any command permanently.
1365
1366   Whether a command is disabled is independent of what key is used to
1367 invoke it; it also applies if the command is invoked using @kbd{M-x}.
1368 Disabling a command has no effect on calling it as a function from Lisp
1369 programs.
1370
1371 @node Syntax
1372 @section The Syntax Table
1373 @cindex syntax table
1374
1375   All the Emacs commands which parse words or balance parentheses are
1376 controlled by the @dfn{syntax table}.  The syntax table specifies which
1377 characters are opening delimiters, which are parts of words, which are
1378 string quotes, and so on.  Actually, each major mode has its own syntax
1379 table (though sometimes related major modes use the same one) which it
1380 installs in each buffer that uses that major mode.  The syntax table
1381 installed in the current buffer is the one that all commands use, so we
1382 call it ``the'' syntax table.  A syntax table is a Lisp object, a vector of
1383 length 256 whose elements are numbers.
1384
1385 @menu
1386 * Entry: Syntax Entry.    What the syntax table records for each character.
1387 * Change: Syntax Change.  How to change the information.
1388 @end menu
1389
1390 @node Syntax Entry
1391 @subsection Information About Each Character
1392
1393   The syntax table entry for a character is a number that encodes six
1394 pieces of information:
1395
1396 @itemize @bullet
1397 @item
1398 The syntactic class of the character, represented as a small integer
1399 @item
1400 The matching delimiter, for delimiter characters only
1401 (the matching delimiter of @samp{(} is @samp{)}, and vice versa)
1402 @item
1403 A flag saying whether the character is the first character of a
1404 two-character comment starting sequence
1405 @item
1406 A flag saying whether the character is the second character of a
1407 two-character comment starting sequence
1408 @item
1409 A flag saying whether the character is the first character of a
1410 two-character comment ending sequence
1411 @item
1412 A flag saying whether the character is the second character of a
1413 two-character comment ending sequence
1414 @end itemize
1415
1416   The syntactic classes are stored internally as small integers, but are
1417 usually described to or by the user with characters.  For example, @samp{(}
1418 is used to specify the syntactic class of opening delimiters.  Here is a
1419 table of syntactic classes, with the characters that specify them.
1420
1421 @table @samp
1422 @item @w{-}
1423 The class of whitespace characters.  Please don't use the formerly
1424 advertised @w{ }, which is not supported by GNU Emacs.
1425 @item w
1426 The class of word-constituent characters.
1427 @item _
1428 The class of characters that are part of symbol names but not words.
1429 This class is represented by @samp{_} because the character @samp{_}
1430 has this class in both C and Lisp.
1431 @item .
1432 The class of punctuation characters that do not fit into any other
1433 special class.
1434 @item (
1435 The class of opening delimiters.
1436 @item )
1437 The class of closing delimiters.
1438 @item '
1439 The class of expression-adhering characters.  These characters are
1440 part of a symbol if found within or adjacent to one, and are part
1441 of a following expression if immediately preceding one, but are like
1442 whitespace if surrounded by whitespace.
1443 @item "
1444 The class of string-quote characters.  They match each other in pairs,
1445 and the characters within the pair all lose their syntactic
1446 significance except for the @samp{\} and @samp{/} classes of escape
1447 characters, which can be used to include a string-quote inside the
1448 string.
1449 @item $
1450 The class of self-matching delimiters.  This is intended for @TeX{}'s
1451 @samp{$}, which is used both to enter and leave math mode.  Thus,
1452 a pair of matching @samp{$} characters surround each piece of math mode
1453 @TeX{} input.  A pair of adjacent @samp{$} characters act like a single
1454 one for purposes of matching.
1455
1456 @item /
1457 The class of escape characters that always just deny the following
1458 character its special syntactic significance.  The character after one
1459 of these escapes is always treated as alphabetic.
1460 @item \
1461 The class of C-style escape characters.  In practice, these are
1462 treated just like @samp{/}-class characters, because the extra
1463 possibilities for C escapes (such as being followed by digits) have no
1464 effect on where the containing expression ends.
1465 @item <
1466 The class of comment-starting characters.  Only single-character
1467 comment starters (such as @samp{;} in Lisp mode) are represented this
1468 way.
1469 @item >
1470 The class of comment-ending characters.  Newline has this syntax in
1471 Lisp mode.
1472 @end table
1473
1474 @vindex parse-sexp-ignore-comments
1475   The characters flagged as part of two-character comment delimiters can
1476 have other syntactic functions most of the time.  For example, @samp{/} and
1477 @samp{*} in C code, when found separately, have nothing to do with
1478 comments.  The comment-delimiter significance overrides when the pair of
1479 characters occur together in the proper order.  Only the list and sexp
1480 commands use the syntax table to find comments; the commands specifically
1481 for comments have other variables that tell them where to find comments.
1482 Moreover, the list and sexp commands notice comments only if
1483 @code{parse-sexp-ignore-comments} is non-@code{nil}.  This variable is set
1484 to @code{nil} in modes where comment-terminator sequences are liable to
1485 appear where there is no comment, for example, in Lisp mode where the
1486 comment terminator is a newline but not every newline ends a comment.
1487
1488 @node Syntax Change
1489 @subsection Altering Syntax Information
1490
1491   It is possible to alter a character's syntax table entry by storing a new
1492 number in the appropriate element of the syntax table, but it would be hard
1493 to determine what number to use.  Emacs therefore provides a command that
1494 allows you to specify the syntactic properties of a character in a
1495 convenient way.
1496
1497 @findex modify-syntax-entry
1498   @kbd{M-x modify-syntax-entry} is the command to change a character's
1499 syntax.  It can be used interactively and is also used by major
1500 modes to initialize their own syntax tables.  Its first argument is the
1501 character to change.  The second argument is a string that specifies the
1502 new syntax.  When called from Lisp code, there is a third, optional
1503 argument, which specifies the syntax table in which to make the change.  If
1504 not supplied, or if this command is called interactively, the third
1505 argument defaults to the current buffer's syntax table.
1506
1507 @enumerate
1508 @item
1509 The first character in the string specifies the syntactic class.  It
1510 is one of the characters in the previous table (@pxref{Syntax Entry}).
1511
1512 @item
1513 The second character is the matching delimiter.  For a character that
1514 is not an opening or closing delimiter, this should be a space, and may
1515 be omitted if no following characters are needed.
1516
1517 @item
1518 The remaining characters are flags.  The flag characters allowed are:
1519
1520 @table @samp
1521 @item 1
1522 Flag this character as the first of a two-character comment starting sequence.
1523 @item 2
1524 Flag this character as the second of a two-character comment starting sequence.
1525 @item 3
1526 Flag this character as the first of a two-character comment ending sequence.
1527 @item 4
1528 Flag this character as the second of a two-character comment ending sequence.
1529 @end table
1530 @end enumerate
1531
1532 @kindex C-h s
1533 @findex describe-syntax
1534   Use @kbd{C-h s} (@code{describe-syntax}) to display a description of
1535 the contents of the current syntax table.  The description of each
1536 character includes both the string you have to pass to
1537 @code{modify-syntax-entry} to set up that character's current syntax,
1538 and some English to explain that string if necessary.
1539
1540 @node Init File
1541 @section The Init File
1542 @cindex init file
1543 @cindex Emacs initialization file
1544 @cindex key rebinding, permanent
1545 @cindex rebinding keys, permanently
1546
1547   When you start Emacs, it normally loads either @file{.xemacs/init.el}
1548 or the file @file{.emacs} (whichever comes first) in your home directory.
1549 This file, if it exists, should contain Lisp code.  It is called your
1550 initialization file or @dfn{init file}.  Use the command line switch
1551 @samp{-q} to tell Emacs whether to load an init file (@pxref{Entering
1552 Emacs}).  Use the command line switch @samp{-user-init-file}
1553 (@pxref{Command Switches}) to tell Emacs to load a different file
1554 instead of @file{~/.xemacs/init.el}/@file{~/.emacs}.
1555
1556 When the init file is read, the variable @code{user-init-file} says
1557 which init file was loaded.
1558
1559   At some sites there is a @dfn{default init file}, which is the
1560 library named @file{default.el}, found via the standard search path for
1561 libraries.  The Emacs distribution contains no such library; your site
1562 may create one for local customizations.  If this library exists, it is
1563 loaded whenever you start Emacs.  But your init file, if any, is loaded
1564 first; if it sets @code{inhibit-default-init} non-@code{nil}, then
1565 @file{default} is not loaded.
1566
1567   If you have a large amount of code in your init file, you should
1568 byte-compile it to @file{~/.xemacs/init.elc} or @file{~/.emacs.elc}.
1569
1570 @menu
1571 * Init Syntax::     Syntax of constants in Emacs Lisp.
1572 * Init Examples::   How to do some things with an init file.
1573 * Terminal Init::   Each terminal type can have an init file.
1574 @end menu
1575
1576 @node Init Syntax
1577 @subsection Init File Syntax
1578
1579   The init file contains one or more Lisp function call
1580 expressions.  Each consists of a function name followed by
1581 arguments, all surrounded by parentheses.  For example, @code{(setq
1582 fill-column 60)} represents a call to the function @code{setq} which is
1583 used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
1584
1585   The second argument to @code{setq} is an expression for the new value
1586 of the variable.  This can be a constant, a variable, or a function call
1587 expression.  In the init file, constants are used most of the time.
1588 They can be:
1589
1590 @table @asis
1591 @item Numbers
1592 Integers are written in decimal, with an optional initial minus sign.
1593
1594 If a sequence of digits is followed by a period and another sequence
1595 of digits, it is interpreted as a floating point number.
1596
1597 The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to
1598 represent numbers in binary, octal, and hexadecimal notation (or radix).
1599
1600 @item Strings
1601 Lisp string syntax is the same as C string syntax with a few extra
1602 features.  Use a double-quote character to begin and end a string constant.
1603
1604 Newlines and special characters may be present literally in strings.  They
1605 can also be represented as backslash sequences: @samp{\n} for newline,
1606 @samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab,
1607 @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
1608 backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
1609 character whose octal code is @var{ooo}.  Backslash and double-quote are
1610 the only characters for which backslash sequences are mandatory.
1611
1612 You can use @samp{\C-} as a prefix for a control character, as in
1613 @samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for
1614 a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
1615 Control-Meta-A.@refill
1616
1617 @item Characters
1618 Lisp character constant syntax consists of a @samp{?} followed by
1619 either a character or an escape sequence starting with @samp{\}.
1620 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
1621 strings and characters are not interchangeable in Lisp; some contexts
1622 require one and some contexts require the other.
1623
1624 @item True
1625 @code{t} stands for `true'.
1626
1627 @item False
1628 @code{nil} stands for `false'.
1629
1630 @item Other Lisp objects
1631 Write a single-quote (') followed by the Lisp object you want.
1632 @end table
1633
1634 @node Init Examples
1635 @subsection Init File Examples
1636
1637   Here are some examples of doing certain commonly desired things with
1638 Lisp expressions:
1639
1640 @itemize @bullet
1641 @item
1642 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
1643 line.
1644
1645 @example
1646 (setq c-tab-always-indent nil)
1647 @end example
1648
1649 Here we have a variable whose value is normally @code{t} for `true'
1650 and the alternative is @code{nil} for `false'.
1651
1652 @item
1653 Make searches case sensitive by default (in all buffers that do not
1654 override this).
1655
1656 @example
1657 (setq-default case-fold-search nil)
1658 @end example
1659
1660 This sets the default value, which is effective in all buffers that do
1661 not have local values for the variable.  Setting @code{case-fold-search}
1662 with @code{setq} affects only the current buffer's local value, which
1663 is probably not what you want to do in an init file.
1664
1665 @item
1666 Make Text mode the default mode for new buffers.
1667
1668 @example
1669 (setq default-major-mode 'text-mode)
1670 @end example
1671
1672 Note that @code{text-mode} is used because it is the command for entering
1673 the mode we want.  A single-quote is written before it to make a symbol
1674 constant; otherwise, @code{text-mode} would be treated as a variable name.
1675
1676 @item
1677 Turn on Auto Fill mode automatically in Text mode and related modes.
1678
1679 @example
1680 (setq text-mode-hook
1681   '(lambda () (auto-fill-mode 1)))
1682 @end example
1683
1684 Here we have a variable whose value should be a Lisp function.  The
1685 function we supply is a list starting with @code{lambda}, and a single
1686 quote is written in front of it to make it (for the purpose of this
1687 @code{setq}) a list constant rather than an expression.  Lisp functions
1688 are not explained here; for mode hooks it is enough to know that
1689 @code{(auto-fill-mode 1)} is an expression that will be executed when
1690 Text mode is entered.  You could replace it with any other expression
1691 that you like, or with several expressions in a row.
1692
1693 @example
1694 (setq text-mode-hook 'turn-on-auto-fill)
1695 @end example
1696
1697 This is another way to accomplish the same result.
1698 @code{turn-on-auto-fill} is a symbol whose function definition is
1699 @code{(lambda () (auto-fill-mode 1))}.
1700
1701 @item
1702 Load the installed Lisp library named @file{foo} (actually a file
1703 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
1704
1705 @example
1706 (load "foo")
1707 @end example
1708
1709 When the argument to @code{load} is a relative pathname, not starting
1710 with @samp{/} or @samp{~}, @code{load} searches the directories in
1711 @code{load-path} (@pxref{Loading}).
1712
1713 @item
1714 Load the compiled Lisp file @file{foo.elc} from your home directory.
1715
1716 @example
1717 (load "~/foo.elc")
1718 @end example
1719
1720 Here an absolute file name is used, so no searching is done.
1721
1722 @item
1723 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
1724
1725 @example
1726 (global-set-key "\C-xl" 'make-symbolic-link)
1727 @end example
1728
1729 or
1730
1731 @example
1732 (define-key global-map "\C-xl" 'make-symbolic-link)
1733 @end example
1734
1735 Note once again the single-quote used to refer to the symbol
1736 @code{make-symbolic-link} instead of its value as a variable.
1737
1738 @item
1739 Do the same thing for C mode only.
1740
1741 @example
1742 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
1743 @end example
1744
1745 @item
1746 Bind the function key @key{F1} to a command in C mode.
1747 Note that the names of function keys must be lower case.
1748
1749 @example
1750 (define-key c-mode-map 'f1 'make-symbolic-link)
1751 @end example
1752
1753 @item
1754 Bind the shifted version of @key{F1} to a command.
1755
1756 @example
1757 (define-key c-mode-map '(shift f1) 'make-symbolic-link)
1758 @end example
1759
1760 @item
1761 Redefine all keys which now run @code{next-line} in Fundamental mode
1762 to run @code{forward-line} instead.
1763
1764 @example
1765 (substitute-key-definition 'next-line 'forward-line
1766                            global-map)
1767 @end example
1768
1769 @item
1770 Make @kbd{C-x C-v} undefined.
1771
1772 @example
1773 (global-unset-key "\C-x\C-v")
1774 @end example
1775
1776 One reason to undefine a key is so that you can make it a prefix.
1777 Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
1778 a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
1779 first.
1780
1781 @item
1782 Make @samp{$} have the syntax of punctuation in Text mode.
1783 Note the use of a character constant for @samp{$}.
1784
1785 @example
1786 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
1787 @end example
1788
1789 @item
1790 Enable the use of the command @code{eval-expression} without confirmation.
1791
1792 @example
1793 (put 'eval-expression 'disabled nil)
1794 @end example
1795 @end itemize
1796
1797 @node Terminal Init
1798 @subsection Terminal-Specific Initialization
1799
1800   Each terminal type can have a Lisp library to be loaded into Emacs when
1801 it is run on that type of terminal.  For a terminal type named
1802 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
1803 found by searching the directories @code{load-path} as usual and trying the
1804 suffixes @samp{.elc} and @samp{.el}.  Normally it appears in the
1805 subdirectory @file{term} of the directory where most Emacs libraries are
1806 kept.@refill
1807
1808   The usual purpose of the terminal-specific library is to define the
1809 escape sequences used by the terminal's function keys using the library
1810 @file{keypad.el}.  See the file
1811 @file{term/vt100.el} for an example of how this is done.@refill
1812
1813   When the terminal type contains a hyphen, only the part of the name
1814 before the first hyphen is significant in choosing the library name.
1815 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
1816 the library @file{term/aaa}.  The code in the library can use
1817 @code{(getenv "TERM")} to find the full terminal type name.@refill
1818
1819 @vindex term-file-prefix
1820   The library's name is constructed by concatenating the value of the
1821 variable @code{term-file-prefix} and the terminal type.  Your init
1822 file can prevent the loading of the terminal-specific library by setting
1823 @code{term-file-prefix} to @code{nil}.  @xref{Init File}.
1824
1825 @vindex term-setup-hook
1826   The value of the variable @code{term-setup-hook}, if not @code{nil}, is
1827 called as a function of no arguments at the end of Emacs initialization,
1828 after both your init file and any terminal-specific library have been
1829 read.  @xref{Init File}.  You can set the value in the init file to
1830 override part of any of the terminal-specific libraries and to define
1831 initializations for terminals that do not have a library.@refill
1832
1833 @node Audible Bell
1834 @section Changing the Bell Sound
1835 @cindex audible bell, changing
1836 @cindex bell, changing
1837 @vindex sound-alist
1838 @findex load-default-sounds
1839 @findex play-sound
1840
1841 You can now change how the audible bell sounds using the variable
1842 @code{sound-alist}.
1843
1844 @code{sound-alist}'s value is an list associating symbols with, among
1845 other things, strings of audio-data.  When @code{ding} is called with
1846 one of the symbols, the associated sound data is played instead of the
1847 standard beep.  This only works if you are logged in on the console of a
1848 machine with audio hardware. To listen to a sound of the provided type,
1849 call the function @code{play-sound} with the argument @var{sound}. You
1850 can also set the volume of the sound with the optional argument 
1851 @var{volume}.@refill
1852 @cindex ding
1853
1854 Each element of @code{sound-alist} is a list describing a sound.
1855 The first element of the list is the name of the sound being defined.
1856 Subsequent elements of the list are alternating keyword/value pairs:
1857
1858 @table @code
1859 @item sound
1860 A string of raw sound data, or the name of another sound to play.   
1861 The symbol @code{t} here means use the default X beep.
1862
1863 @item volume
1864 An integer from 0-100, defaulting to @code{bell-volume}.
1865
1866 @item pitch
1867 If using the default X beep, the pitch (Hz) to generate.
1868
1869 @item duration
1870 If using the default X beep, the duration (milliseconds).
1871 @end table
1872
1873 For compatibility, elements of `sound-alist' may also be of the form:
1874
1875 @example
1876 ( @var{sound-name} . @var{<sound>} )
1877 ( @var{sound-name} @var{<volume>} @var{<sound>} )
1878 @end example
1879
1880 You should probably add things to this list by calling the function
1881 @code{load-sound-file}.
1882
1883 Note that you can only play audio data if running on the console screen
1884 of a machine with audio hardware which emacs understands, which at this
1885 time means a Sun SparcStation, SGI, or HP9000s700.
1886
1887 Also note that the pitch, duration, and volume options are available
1888 everywhere, but most X servers ignore the `pitch' option.
1889
1890 @vindex bell-volume
1891 The variable @code{bell-volume} should be an integer from 0 to 100,
1892 with 100 being loudest, which controls how loud the sounds emacs makes
1893 should be.  Elements of the @code{sound-alist} may override this value.
1894 This variable applies to the standard X bell sound as well as sound files.
1895
1896 If the symbol @code{t} is in place of a sound-string, Emacs uses the
1897 default X beep.  This allows you to define beep-types of 
1898 different volumes even when not running on the console.
1899
1900 @findex load-sound-file
1901 You can add things to this list by calling the function
1902 @code{load-sound-file}, which reads in an audio-file and adds its data to
1903 the sound-alist. You can specify the sound with the @var{sound-name}
1904 argument and the file into which the sounds are loaded with the
1905 @var{filename} argument. The optional @var{volume} argument sets the
1906 volume.
1907
1908 @code{load-sound-file (@var{filename sound-name} &optional @var{volume})}
1909
1910 To load and install some sound files as beep-types, use the function
1911 @code{load-default-sounds} (note that this only works if you are on
1912 display 0 of a machine with audio hardware).
1913
1914 The following beep-types are used by Emacs itself. Other Lisp
1915 packages may use other beep types, but these are the ones that the C
1916 kernel of Emacs uses.
1917
1918 @table @code
1919 @item auto-save-error
1920 An auto-save does not succeed
1921
1922 @item command-error
1923 The Emacs command loop catches an error
1924
1925 @item undefined-key
1926 You type a key that is undefined
1927
1928 @item undefined-click
1929 You use an undefined mouse-click combination
1930
1931 @item no-completion
1932 Completion was not possible
1933
1934 @item y-or-n-p
1935 You type something other than the required @code{y} or @code{n}
1936
1937 @item yes-or-no-p       
1938 You type something other than @code{yes} or @code{no}
1939 @end table
1940
1941 @comment  node-name,  next,  previous,  up
1942 @node Faces
1943 @section Faces
1944
1945 XEmacs has objects called extents and faces.  An @dfn{extent}
1946 is a region of text and a @dfn{face} is a collection of textual
1947 attributes, such as fonts and colors.  Every extent is displayed in some
1948 face; therefore, changing the properties of a face immediately updates the
1949 display of all associated extents.  Faces can be frame-local: you can
1950 have a region of text that displays with completely different
1951 attributes when its buffer is viewed from a different X window.
1952
1953 The display attributes of faces may be specified either in Lisp or through
1954 the X resource manager.
1955
1956 @subsection Customizing Faces
1957
1958 You can change the face of an extent with the functions in
1959 this section.  All the functions prompt for a @var{face} as an
1960 argument; use completion for a list of possible values.
1961
1962 @table @kbd
1963 @item M-x invert-face
1964 Swap the foreground and background colors of the given @var{face}.
1965 @item M-x make-face-bold
1966 Make the font of the given @var{face} bold.  When called from a
1967 program, returns @code{nil} if this is not possible.
1968 @item M-x make-face-bold-italic
1969 Make the font of the given @var{face} bold italic.  
1970 When called from a program, returns @code{nil} if not possible.
1971 @item M-x make-face-italic
1972 Make the font of the given @var{face} italic.  
1973 When called from a program, returns @code{nil} if not possible.
1974 @item M-x make-face-unbold
1975 Make the font of the given @var{face} non-bold.  
1976 When called from a program, returns @code{nil} if not possible.
1977 @item M-x make-face-unitalic
1978 Make the font of the given @var{face} non-italic.
1979 When called from a program, returns @code{nil} if not possible.
1980 @item M-x make-face-larger
1981 Make the font of the given @var{face} a little larger.
1982 When called from a program, returns @code{nil} if not possible.
1983 @item M-x make-face-smaller
1984 Make the font of the given @var{face} a little smaller.
1985 When called from a program, returns @code{nil} if not possible.
1986 @item M-x set-face-background 
1987 Change the background color of the given @var{face}.
1988 @item M-x set-face-background-pixmap
1989 Change the background pixmap of the given @var{face}.
1990 @item M-x set-face-font 
1991 Change the font of the given @var{face}.
1992 @item M-x set-face-foreground
1993 Change the foreground color of the given @var{face}.
1994 @item M-x set-face-underline-p
1995 Change whether the given @var{face} is underlined.
1996 @end table
1997
1998 @findex make-face-larger
1999 @findex make-face-smaller
2000
2001 @findex invert-face
2002 You can exchange the foreground and background color of the selected
2003 @var{face} with the function @code{invert-face}. If the face does not
2004 specify both foreground and background, then its foreground and
2005 background are set to the background and foreground of the default face.
2006 When calling this from a program, you can supply the optional argument 
2007 @var{frame} to specify which frame is affected; otherwise, all frames
2008 are affected.
2009
2010 @findex make-face-bold
2011 @findex make-face-bold-italic
2012 @findex make-face-italic
2013 @findex make-face-unbold
2014 @findex make-face-unitalic
2015 @vindex face-frob-from-locale-first
2016 The work of @code{make-face-bold}, @code{make-face-bold-italic},
2017 @code{make-face-italic}, @code{make-face-unbold},
2018 @code{make-face-unitalic} functions is affected by
2019 @code{face-frob-from-locale-first} variable.  If it is @code{nil}, those
2020 functions first try to manipulate device specific data like X font names
2021 to obtain the desired font face specification.  This may be unsuitable
2022 in environments using different font face specifications for different
2023 frames, non-Mule environments in particular.
2024
2025 If the variable is non-@code{nil}, those functions first try to figure
2026 out whether the face font is the same as one of predefined faces:
2027 @code{default}, @code{bold}, @code{italic}, @code{bold-italic}.  If it
2028 is the same, then the new face font specification is set to be the same
2029 as that of a corresponding predefined face.  Thus if the predefined face
2030 is set up properly for different frames, the same will hold for the face
2031 being changed by the functions.  This is the behavior one might desire
2032 in non-Mule environments mentioned above: face being changed still looks
2033 right in all frames.
2034
2035 How predefined faces might be set up for different frames in such an
2036 environments is described in @ref{Face Resources}.
2037
2038 @findex set-face-background
2039 You can set the background color of the specified @var{face} with the
2040 function @code{set-face-background}.  The argument @code{color} should
2041 be a string, the name of a color.  When called from a program, if the
2042 optional @var{frame} argument is provided, the face is changed only 
2043 in that frame; otherwise, it is changed in all frames.
2044
2045 @findex set-face-background-pixmap
2046 You can set the background pixmap of the specified @var{face} with the
2047 function @code{set-face-background-pixmap}.  The pixmap argument
2048 @var{name} should be a string, the name of a file of pixmap data.  The
2049 directories listed in the @code{x-bitmap-file-path} variable are
2050 searched.  The bitmap may also be a list of the form @code{(@var{width
2051 height data})}, where @var{width} and @var{height} are the size in
2052 pixels, and @var{data} is a string containing the raw bits of the
2053 bitmap.  If the optional @var{frame} argument is provided, the face is
2054 changed only in that frame; otherwise, it is changed in all frames.
2055
2056 The variable @code{x-bitmap-file-path} takes as a value a list of the
2057 directories in which X bitmap files may be found.  If the value is
2058 @code{nil}, the list is initialized from the @code{*bitmapFilePath}
2059 resource.
2060
2061 If the environment variable @b{XBMLANGPATH} is set, then it is consulted
2062 before the @code{x-bitmap-file-path} variable.
2063
2064 @findex set-face-font
2065 You can set the font of the specified @var{face} with the function
2066 @code{set-face-font}.  The @var{font} argument should be a string, the
2067 name of a font.  When called from a program, if the
2068 optional @var{frame} argument is provided, the face is changed only 
2069 in that frame; otherwise, it is changed in all frames.
2070
2071 @findex set-face-foreground 
2072 You can set the foreground color of the specified @var{face} with the
2073 function @code{set-face-foreground}.  The argument @var{color} should be
2074 a string, the name of a color.  If the optional @var{frame} argument is
2075 provided, the face is changed only in that frame; otherwise, it is
2076 changed in all frames.
2077
2078 @findex set-face-underline-p
2079 You can set underline the specified @var{face} with the function
2080 @code{set-face-underline-p}. The argument @var{underline-p} can be used
2081 to make underlining an attribute of the face or not. If the optional
2082 @var{frame} argument is provided, the face is changed only in that
2083 frame; otherwise, it is changed in all frames.
2084
2085 @node Frame Components
2086 @section Frame Components
2087
2088 You can control the presence and position of most frame components, such
2089 as the menubar, toolbars, and gutters.
2090
2091 This section is not written yet.  Try the Lisp Reference Manual:
2092 @ref{Menubar,,,lispref,}, @ref{Toolbar Intro,,,lispref,}, and
2093 @ref{Gutter Intro,,,lispref,}.
2094
2095 @node X Resources
2096 @section X Resources
2097 @cindex X resources
2098 @findex x-create-frame
2099
2100 Historically, XEmacs has used the X resource application class @samp{Emacs}
2101 for its resources.  Unfortunately, GNU Emacs uses the same application
2102 class, and resources are not compatible between the two Emacsen.  This
2103 sharing of the application class often leads to trouble if you want to
2104 run both variants.
2105
2106 Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
2107 any XEmacs resources in the resource database when the X connection is
2108 initialized.  Otherwise, it will use the class @samp{Emacs} for
2109 backwards compatibility.  The variable @code{x-emacs-application-class}
2110 may be consulted to determine the application class being used.
2111
2112 The examples in this section assume the application class is @samp{Emacs}.
2113
2114 The Emacs resources are generally set per-frame. Each Emacs frame can have 
2115 its own name or the same name as another, depending on the name passed to the 
2116 @code{make-frame} function.
2117
2118 You can specify resources for all frames with the syntax:
2119
2120 @example
2121 Emacs*parameter: value
2122 @end example
2123 @noindent
2124
2125 or
2126
2127 @example
2128 Emacs*EmacsFrame.parameter:value
2129 @end example
2130 @noindent
2131
2132 You can specify resources for a particular frame with the syntax:
2133
2134 @example
2135 Emacs*FRAME-NAME.parameter: value
2136 @end example
2137 @noindent
2138
2139 @menu
2140 * Geometry Resources::     Controlling the size and position of frames.
2141 * Iconic Resources::       Controlling whether frames come up iconic.
2142 * Resource List::          List of resources settable on a frame or device.
2143 * Face Resources::         Controlling faces using resources.
2144 * Widgets::                The widget hierarchy for XEmacs.
2145 * Menubar Resources::      Specifying resources for the menubar.
2146 @end menu
2147
2148 @node Geometry Resources
2149 @subsection Geometry Resources
2150
2151 To make the default size of all Emacs frames be 80 columns by 55 lines,
2152 do this:
2153
2154 @example
2155 Emacs*EmacsFrame.geometry: 80x55
2156 @end example
2157 @noindent
2158
2159 To set the geometry of a particular frame named @samp{fred}, do this:
2160
2161 @example
2162 Emacs*fred.geometry: 80x55
2163 @end example
2164 @noindent
2165
2166 Important! Do not use the following syntax:
2167
2168 @example
2169 Emacs*geometry: 80x55
2170 @end example
2171 @noindent
2172
2173 You should never use @code{*geometry} with any X application. It does
2174 not say "make the geometry of Emacs be 80 columns by 55 lines."  It
2175 really says, "make Emacs and all subwindows thereof be 80x55 in whatever
2176 units they care to measure in."  In particular, that is both telling the
2177 Emacs text pane to be 80x55 in characters, and telling the menubar pane
2178 to be 80x55 pixels, which is surely not what you want.
2179
2180 As a special case, this geometry specification also works (and sets the
2181 default size of all Emacs frames to 80 columns by 55 lines):
2182
2183 @example
2184 Emacs.geometry: 80x55
2185 @end example
2186 @noindent
2187
2188 since that is the syntax used with most other applications (since most
2189 other applications have only one top-level window, unlike Emacs).  In
2190 general, however, the top-level shell (the unmapped ApplicationShell
2191 widget named @samp{Emacs} that is the parent of the shell widgets that
2192 actually manage the individual frames) does not have any interesting
2193 resources on it, and you should set the resources on the frames instead.
2194
2195 The @code{-geometry} command-line argument sets only the geometry of the
2196 initial frame created by Emacs.
2197
2198 A more complete explanation of geometry-handling is
2199
2200 @itemize @bullet
2201 @item
2202 The @code{-geometry} command-line option sets the @code{Emacs.geometry}
2203 resource, that is, the geometry of the ApplicationShell.
2204
2205 @item
2206 For the first frame created, the size of the frame is taken from the
2207 ApplicationShell if it is specified, otherwise from the geometry of the
2208 frame.
2209
2210 @item
2211 For subsequent frames, the order is reversed: First the frame, and then
2212 the ApplicationShell.
2213
2214 @item
2215 For the first frame created, the position of the frame is taken from the
2216 ApplicationShell (@code{Emacs.geometry}) if it is specified, otherwise
2217 from the geometry of the frame.
2218
2219 @item
2220 For subsequent frames, the position is taken only from the frame, and 
2221 never from the ApplicationShell.
2222 @end itemize
2223
2224 This is rather complicated, but it does seem to provide the most
2225 intuitive behavior with respect to the default sizes and positions of
2226 frames created in various ways.
2227
2228 @node Iconic Resources
2229 @subsection Iconic Resources
2230
2231 Analogous to @code{-geometry}, the @code{-iconic} command-line option
2232 sets the iconic flag of the ApplicationShell (@code{Emacs.iconic}) and
2233 always applies to the first frame created regardless of its name.
2234 However, it is possible to set the iconic flag on particular frames (by
2235 name) by using the @code{Emacs*FRAME-NAME.iconic} resource.
2236
2237 @node Resource List
2238 @subsection Resource List
2239
2240 Emacs frames accept the following resources:
2241
2242 @table @asis
2243 @item @code{geometry} (class @code{Geometry}): string
2244 Initial geometry for the frame.  @xref{Geometry Resources}, for a
2245 complete discussion of how this works.
2246
2247 @item @code{iconic} (class @code{Iconic}): boolean
2248 Whether this frame should appear in the iconified state.
2249
2250 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int
2251 How many blank pixels to leave between the text and the edge of the 
2252 window.
2253
2254 @item @code{interline} (class @code{Interline}): int
2255 How many pixels to leave between each line (may not be implemented).
2256
2257 @item @code{menubar} (class @code{Menubar}): boolean
2258 Whether newly-created frames should initially have a menubar.  Set to
2259 true by default.
2260
2261 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean
2262 Whether XEmacs should leave the initial frame unmapped when it starts
2263 up.  This is useful if you are starting XEmacs as a server (e.g. in
2264 conjunction with gnuserv or the external client widget).  You can also
2265 control this with the @code{-unmapped} command-line option.
2266
2267 @item @code{barCursor} (class @code{BarColor}): boolean
2268 Whether the cursor should be displayed as a bar, or the traditional box.
2269
2270 @item @code{cursorColor} (class @code{CursorColor}): color-name
2271 The color of the text cursor.
2272
2273 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer
2274 How wide the vertical scrollbars should be, in pixels; 0 means no
2275 vertical scrollbars.  You can also use a resource specification of the
2276 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources:
2277 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid),
2278 or @code{*Scrollbar.thickness} (Athena).  We don't recommend that you
2279 use the toolkit resources, though, because they're dependent on how
2280 exactly your particular build of XEmacs was configured.
2281
2282 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer
2283 How high the horizontal scrollbars should be, in pixels; 0 means no
2284 horizontal scrollbars.  You can also use a resource specification of the
2285 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources:
2286 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid),
2287 or @code{*Scrollbar.thickness} (Athena).  We don't recommend that you use
2288 the toolkit resources, though, because they're dependent on how exactly
2289 your particular build of XEmacs was configured.
2290
2291 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string
2292 Where the horizontal and vertical scrollbars should be positioned.  This
2293 should be one of the four strings @samp{BOTTOM_LEFT},
2294 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}.  Default is
2295 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and
2296 @samp{BOTTOM_LEFT} for the Athena scrollbars.
2297
2298 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer
2299 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer
2300 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer
2301 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer
2302 Height and width of the four possible toolbars.
2303
2304 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name
2305 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name
2306 Color of the top and bottom shadows for the toolbars.  NOTE: These resources
2307 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the
2308 toolbars at the top and bottom of the frame)!  Rather, they affect the top
2309 and bottom shadows around the edges of all four kinds of toolbars.
2310
2311 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name
2312 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name
2313 Pixmap of the top and bottom shadows for the toolbars.  If set, these
2314 resources override the corresponding color resources. NOTE: These
2315 resources do @emph{not} have anything to do with the top and bottom
2316 toolbars (i.e. the toolbars at the top and bottom of the frame)!
2317 Rather, they affect the top and bottom shadows around the edges of all
2318 four kinds of toolbars.
2319
2320 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer
2321 Thickness of the shadows around the toolbars, in pixels.
2322
2323 @item @code{visualBell} (class @code{VisualBell}): boolean
2324 Whether XEmacs should flash the screen rather than making an audible beep.
2325
2326 @item @code{bellVolume} (class @code{BellVolume}): integer
2327 Volume of the audible beep.
2328
2329 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean
2330 Whether XEmacs should set the backing-store attribute of the X windows
2331 it creates.  This increases the memory usage of the X server but decreases
2332 the amount of X traffic necessary to update the screen, and is useful
2333 when the connection to the X server goes over a low-bandwidth line
2334 such as a modem connection.
2335 @end table
2336
2337 Emacs devices accept the following resources:
2338
2339 @table @asis
2340 @item @code{textPointer} (class @code{Cursor}): cursor-name
2341 The cursor to use when the mouse is over text.  This resource is used to
2342 initialize the variable @code{x-pointer-shape}.
2343
2344 @item @code{selectionPointer} (class @code{Cursor}): cursor-name
2345 The cursor to use when the mouse is over a selectable text region (an
2346 extent with the @samp{highlight} property; for example, an Info
2347 cross-reference).  This resource is used to initialize the variable
2348 @code{x-selection-pointer-shape}.
2349
2350 @item @code{spacePointer} (class @code{Cursor}): cursor-name
2351 The cursor to use when the mouse is over a blank space in a buffer (that
2352 is, after the end of a line or after the end-of-file).  This resource is
2353 used to initialize the variable @code{x-nontext-pointer-shape}.
2354
2355 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name
2356 The cursor to use when the mouse is over a modeline.  This resource is
2357 used to initialize the variable @code{x-mode-pointer-shape}.
2358
2359 @item @code{gcPointer} (class @code{Cursor}): cursor-name
2360 The cursor to display when a garbage-collection is in progress.  This
2361 resource is used to initialize the variable @code{x-gc-pointer-shape}.
2362
2363 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name
2364 The cursor to use when the mouse is over the scrollbar.  This resource
2365 is used to initialize the variable @code{x-scrollbar-pointer-shape}.
2366
2367 @item @code{pointerColor} (class @code{Foreground}): color-name
2368 @itemx @code{pointerBackground} (class @code{Background}): color-name
2369 The foreground and background colors of the mouse cursor.  These
2370 resources are used to initialize the variables
2371 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}.
2372 @end table
2373
2374 @node Face Resources
2375 @subsection Face Resources
2376
2377 The attributes of faces are also per-frame. They can be specified as:
2378
2379 @example
2380 Emacs.FACE_NAME.parameter: value
2381 @end example
2382 @noindent
2383
2384 or
2385
2386 @example
2387 Emacs*FRAME_NAME.FACE_NAME.parameter: value
2388 @end example
2389 @noindent
2390
2391 Faces accept the following resources:
2392
2393 @table @asis
2394 @item @code{attributeFont} (class @code{AttributeFont}): font-name
2395 The font of this face.
2396
2397 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name
2398 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name
2399 The foreground and background colors of this face.
2400
2401 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name
2402 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of Emacs
2403 supports @sc{xpm}), to use as a background stipple.
2404
2405 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean
2406 Whether text in this face should be underlined.
2407 @end table
2408
2409 All text is displayed in some face, defaulting to the face named
2410 @code{default}.  To set the font of normal text, use
2411 @code{Emacs*default.attributeFont}. To set it in the frame named
2412 @code{fred}, use @code{Emacs*fred.default.attributeFont}.
2413
2414 These are the names of the predefined faces:
2415
2416 @table @code
2417 @item default
2418 Everything inherits from this.
2419
2420 @item bold
2421 If this is not specified in the resource database, Emacs tries to find a
2422 bold version of the font of the default face.
2423
2424 @item italic
2425 If this is not specified in the resource database, Emacs tries to find
2426 an italic version of the font of the default face.
2427
2428 @item bold-italic
2429 If this is not specified in the resource database, Emacs tries to find a
2430 bold-italic version of the font of the default face.
2431
2432 @item modeline
2433 This is the face that the modeline is displayed in.  If not specified in
2434 the resource database, it is determined from the default face by
2435 reversing the foreground and background colors.
2436
2437 @item highlight
2438 This is the face that highlighted extents (for example, Info
2439 cross-references and possible completions, when the mouse passes over
2440 them) are displayed in.
2441
2442 @item left-margin
2443 @itemx right-margin
2444 These are the faces that the left and right annotation margins are
2445 displayed in.
2446
2447 @item zmacs-region
2448 This is the face that mouse selections are displayed in.
2449  
2450 @item isearch
2451 This is the face that the matched text being searched for is displayed
2452 in.
2453
2454 @item info-node
2455 This is the face of info menu items.  If unspecified, it is copied from
2456 @code{bold-italic}.
2457
2458 @item info-xref
2459 This is the face of info cross-references.  If unspecified, it is copied
2460 from @code{bold}. (Note that, when the mouse passes over a
2461 cross-reference, the cross-reference's face is determined from a
2462 combination of the @code{info-xref} and @code{highlight} faces.)
2463 @end table
2464
2465 Other packages might define their own faces; to see a list of all faces,
2466 use any of the interactive face-manipulation commands such as
2467 @code{set-face-font} and type @samp{?} when you are prompted for the
2468 name of a face.
2469
2470 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not
2471 specified in the resource database, then XEmacs attempts to derive them
2472 from the font of the default face.  It can only succeed at this if you
2473 have specified the default font using the XLFD (X Logical Font
2474 Description) format, which looks like
2475
2476 @example
2477 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2478 @end example
2479 @noindent
2480
2481 If you use any of the other, less strict font name formats, some of which
2482 look like
2483
2484 @example
2485 lucidasanstypewriter-12
2486 fixed
2487 9x13
2488 @end example
2489
2490 then XEmacs won't be able to guess the names of the bold and italic
2491 versions.  All X fonts can be referred to via XLFD-style names, so you
2492 should use those forms.  See the man pages for @samp{X(1)},
2493 @samp{xlsfonts(1)}, and @samp{xfontsel(1)}.
2494
2495 @node Widgets
2496 @subsection Widgets
2497
2498 There are several structural widgets between the terminal EmacsFrame
2499 widget and the top level ApplicationShell; the exact names and types of
2500 these widgets change from release to release (for example, they changed
2501 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
2502 subject to further change in the future, so you should avoid mentioning
2503 them in your resource database.  The above-mentioned syntaxes should be
2504 forward- compatible.  As of 19.13, the exact widget hierarchy is as
2505 follows:
2506
2507 @example
2508 INVOCATION-NAME            "shell"       "container"     FRAME-NAME
2509 x-emacs-application-class  "EmacsShell"  "EmacsManager"  "EmacsFrame"
2510 @end example
2511
2512 where INVOCATION-NAME is the terminal component of the name of the
2513 XEmacs executable (usually @samp{xemacs}), and
2514 @samp{x-emacs-application-class} is generally @samp{Emacs}.
2515
2516 @node Menubar Resources
2517 @subsection Menubar Resources
2518
2519 As the menubar is implemented as a widget which is not a part of XEmacs
2520 proper, it does not use the face mechanism for specifying fonts and
2521 colors: It uses whatever resources are appropriate to the type of widget
2522 which is used to implement it.
2523
2524 If Emacs was compiled to use only the Lucid Motif-lookalike menu widgets,
2525 then one way to specify the font of the menubar would be
2526
2527 @example
2528 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2529 @end example
2530
2531 If both the Lucid Motif-lookalike menu widgets and X Font Sets are 
2532 configured to allow multilingual menubars, then one uses
2533
2534 @example
2535 *menubar*FontSet:       -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
2536                         -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
2537 @end example
2538
2539 That would specify fonts for a Japanese menubar.  Specifying only one
2540 XLFD is acceptable; specifying more than one for a given registry
2541 (language) is also allowed.  When X Font Sets are configured, some .font
2542 resources (eg, menubars) are ignored in favor of the corresponding
2543 .fontSet resources.
2544
2545 If the Motif library is being used, then one would have to use 
2546
2547 @example
2548 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
2549 @end example
2550
2551 because the Motif library uses the @code{fontList} resource name instead
2552 of @code{font}, which has subtly different semantics.
2553
2554 The same is true of the scrollbars: They accept whichever resources are 
2555 appropriate for the toolkit in use.