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