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