Mercurial > hg > xemacs-beta
annotate man/xemacs/custom.texi @ 5167:e374ea766cc1
clean up, rearrange allocation statistics code
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-03-21 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (assert_proper_sizing):
* alloc.c (c_readonly):
* alloc.c (malloced_storage_size):
* alloc.c (fixed_type_block_overhead):
* alloc.c (lisp_object_storage_size):
* alloc.c (inc_lrecord_stats):
* alloc.c (dec_lrecord_stats):
* alloc.c (pluralize_word):
* alloc.c (object_memory_usage_stats):
* alloc.c (Fobject_memory_usage):
* alloc.c (compute_memusage_stats_length):
* alloc.c (disksave_object_finalization_1):
* alloc.c (Fgarbage_collect):
* mc-alloc.c:
* mc-alloc.c (mc_alloced_storage_size):
* mc-alloc.h:
No functionality change here. Collect the allocations-statistics
code that was scattered throughout alloc.c into one place. Add
remaining section headings so that all sections have headings
clearly identifying the start of the section and its purpose.
Expose mc_alloced_storage_size() even when not MEMORY_USAGE_STATS;
this fixes build problems and is related to the export of
lisp_object_storage_size() and malloced_storage_size() when
non-MEMORY_USAGE_STATS in the previous change set.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Sun, 21 Mar 2010 04:41:49 -0500 |
| parents | 5502045ec510 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 |
| 3387 | 2 @c FIXME -- we demand a detail menu! |
| 3 | |
| 428 | 4 @node Customization, Quitting, Emulation, Top |
| 5 @chapter Customization | |
| 6 @cindex customization | |
| 7 | |
| 8 This chapter talks about various topics relevant to adapting the | |
| 9 behavior of Emacs in minor ways. | |
| 10 | |
| 11 All kinds of customization affect only the particular Emacs job that you | |
| 442 | 12 do them in. They are completely lost when you kill the Emacs job, and |
| 13 have no effect on other Emacs jobs you may run at the same time or | |
| 14 later. The only way an Emacs job can affect anything outside of it is | |
| 15 by writing a file; in particular, the only way to make a customization | |
| 16 `permanent' is to put something in your init file or other appropriate | |
| 17 file to do the customization in each session. @xref{Init File}. | |
| 428 | 18 |
| 19 @menu | |
| 20 * Minor Modes:: Each minor mode is one feature you can turn on | |
| 21 independently of any others. | |
| 775 | 22 * Behaviors:: Like minor modes, behaviors are independent of other |
| 23 features, but behaviors are usually enabled globally, | |
| 24 while minor modes are per-buffer and often temporary. | |
| 428 | 25 * Variables:: Many Emacs commands examine Emacs variables |
| 26 to decide what to do; by setting variables, | |
| 27 you can control their functioning. | |
| 28 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes | |
| 29 to be replayed with a single command. | |
| 30 * Key Bindings:: The keymaps say what command each key runs. | |
| 31 By changing them, you can "redefine keys". | |
| 32 * Syntax:: The syntax table controls how words and expressions | |
| 33 are parsed. | |
| 442 | 34 * Init File:: How to write common customizations in the init file. |
| 35 * Audible Bell:: Changing how Emacs sounds the bell. | |
| 36 * Faces:: Changing the fonts and colors of a region of text. | |
| 37 * Frame Components:: Controlling the presence and positions of the | |
| 38 menubar, toolbars, and gutters. | |
| 440 | 39 * X Resources:: X resources controlling various aspects of the |
| 428 | 40 behavior of XEmacs. |
| 41 @end menu | |
| 42 | |
| 43 @node Minor Modes | |
| 44 @section Minor Modes | |
| 45 @cindex minor modes | |
| 46 | |
| 47 @cindex mode line | |
| 2736 | 48 Minor modes are common options which may be useful in many major |
| 49 modes, but which may need to be enabled or disabled independently of the | |
| 50 major mode. (This may be because user preferences for the feature vary, | |
| 51 or because the feature is sometimes more of a hindrance than an aid | |
| 52 depending on the specific content of the buffer.) For example, Auto | |
| 53 Fill mode is a minor mode in which @key{SPC} automatically breaks lines | |
| 54 between words at the right margin | |
| 55 as you type. Minor modes are independent of each other and of | |
| 428 | 56 the selected major mode. Most minor modes inform you in the mode line |
| 57 when they are on; for example, @samp{Fill} in the mode line means that | |
| 58 Auto Fill mode is on. | |
| 59 | |
| 60 Append @code{-mode} to the name of a minor mode to get the name of a | |
| 61 command function that turns the mode on or off. Thus, the command to | |
| 62 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These | |
| 63 commands are usually invoked with @kbd{M-x}, but you can bind keys to them | |
| 64 if you wish. With no argument, the function turns the mode on if it was | |
| 2736 | 65 off and off if it was on. This is called @dfn{toggling}. A positive |
| 428 | 66 argument always turns the mode on, and an explicit zero argument or a |
| 67 negative argument always turns it off. | |
| 68 | |
| 2736 | 69 @c #### maybe this list should be extended and moved to its own node? |
| 70 | |
| 428 | 71 @cindex Auto Fill mode |
| 72 @findex auto-fill-mode | |
| 73 Auto Fill mode allows you to enter filled text without breaking lines | |
| 74 explicitly. Emacs inserts newlines as necessary to prevent lines from | |
| 75 becoming too long. @xref{Filling}. | |
| 76 | |
| 2736 | 77 @cindex Filladapt mode |
| 78 @findex filladapt-mode | |
| 79 Filladapt mode is an extension of Auto Fill mode which recognizes | |
| 80 @dfn{line prefixes} and automatically prepends them when automatically | |
| 81 breaking lines. Filladapt mode is smart enough to recognize common | |
| 82 idioms for bullets (e.g., leading isolated hyphens) and enumerated | |
| 83 paragraphs, and insert appropriate leading whitespace (and omit the | |
| 84 bullet!) It also does a good job of recognizing common quotation styles | |
| 85 in email. Filladapt mode must be enabled in addition to Auto Fill | |
| 86 mode. If Auto Fill mode is disabled, Filladapt mode will be | |
| 87 inactivated, but the indicator will remain in the modeline. | |
| 88 | |
| 428 | 89 @cindex Overwrite mode |
| 90 @findex overwrite-mode | |
| 91 Overwrite mode causes ordinary printing characters to replace existing | |
| 92 text instead of moving it to the right. For example, if point is in | |
| 93 front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite | |
| 94 mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill | |
| 95 | |
| 2736 | 96 @cindex Pending Delete mode |
| 97 @findex pending-delete-mode | |
| 98 Pending Delete mode cause buffer insertions and deletions to replace the | |
| 99 active region (with nothing, for deletions). This is the common | |
| 100 behavior in most modern programs, but conflicts with the ``lightweight | |
| 101 selections'' used in the X Window System. | |
| 102 | |
| 428 | 103 @cindex Abbrev mode |
| 104 @findex abbrev-mode | |
| 105 Abbrev mode allows you to define abbreviations that automatically expand | |
| 106 as you type them. For example, @samp{amd} might expand to @samp{abbrev | |
| 107 mode}. @xref{Abbrevs}, for full information. | |
| 108 | |
| 775 | 109 @c Updated for 21.5.6 2002/03/13 sjt |
| 110 @node Behaviors | |
| 111 @section Behaviors | |
| 112 @cindex behavior | |
| 113 | |
| 2736 | 114 @dfn{Behaviors} are an alternative interface to minor modes. The toggle |
| 115 interface emphasizes the case-specific nature of a minor mode: use it | |
| 116 with @emph{this} major mode but not in @emph{those} buffers. However, | |
| 117 this is inconvenient for behavior that depends on user preference. | |
| 118 For example, someone who discovers filladapt and really | |
| 775 | 119 likes it must toggle it separately in each buffer. On the other hand, |
| 120 after trying it for a while she might like to disable it everywhere, | |
| 2736 | 121 having decided it doesn't work very well for her. |
| 122 | |
| 123 Use of mode hooks will invoke the minor mode automatically in the | |
| 124 future, but this is inconvenient (you must switch tasks to editing the | |
| 125 init file) and doesn't help with existing buffers in the session. The | |
| 126 behavior interface addresses this problem. The command | |
| 127 @code{enable-behavior} prompts (with completion) for a registered | |
| 128 behavior (denoted by a symbol), and enables it. Conversely, | |
| 129 @code{disable-behavior} prompts for a behavior, and disables it. | |
| 130 | |
| 131 @c #### This belongs in the Lispref in the description of creating | |
| 132 @c packages or in customize or both. | |
| 133 | |
| 134 @c The package developer will register behaviors with XEmacs. Then the | |
| 135 @c user invokes the @code{enable-behavior} and @code{disable-behavior} | |
| 136 @c functions to enable or disable a given behavior. The behavior registry | |
| 137 @c was introduced in XEmacs 21.5.6. | |
| 138 @c | |
| 4488 | 139 @c @defun enable-behavior behavior &optional force |
| 2736 | 140 @c Called interactively, prompt the user, read a behavior symbol name with |
| 141 @c completion for @var{behavior}, and take @var{force} from the prefix | |
| 142 @c argument. Then enable the behavior registered under the symbol | |
| 143 @c @var{behavior}. | |
| 144 @c | |
| 145 @c The optional argument @var{force} is unimplemented in 21.5.6. | |
| 146 @c @end defun | |
| 147 @c | |
| 148 @c @defun disable-behavior behavior &optional force | |
| 149 @c Called interactively, prompt the user, read a behavior symbol name with | |
| 150 @c completion for @var{behavior}, and take @var{force} from the prefix | |
| 151 @c argument. Then disable the behavior registered under the symbol | |
| 152 @c @var{behavior}. | |
| 153 @c | |
| 154 @c The optional argument @var{force} is unimplemented in 21.5.6. | |
| 155 @c @end defun | |
| 775 | 156 |
| 157 | |
| 428 | 158 @node Variables |
| 159 @section Variables | |
| 160 @cindex variable | |
| 161 @cindex option | |
| 162 | |
| 163 A @dfn{variable} is a Lisp symbol which has a value. Variable names | |
| 164 can contain any characters, but by convention they are words separated | |
| 165 by hyphens. A variable can also have a documentation string, which | |
| 166 describes what kind of value it should have and how the value will be | |
| 167 used. | |
| 168 | |
| 169 Lisp allows any variable to have any kind of value, but most variables | |
| 170 that Emacs uses require a value of a certain type. Often the value has | |
| 171 to be a string or a number. Sometimes we say that a certain feature is | |
| 172 turned on if a variable is ``non-@code{nil},'' meaning that if the | |
| 173 variable's value is @code{nil}, the feature is off, but the feature is | |
| 174 on for @i{any} other value. The conventional value to turn on the | |
| 175 feature---since you have to pick one particular value when you set the | |
| 176 variable---is @code{t}. | |
| 177 | |
| 178 Emacs uses many Lisp variables for internal recordkeeping, as any Lisp | |
| 179 program must, but the most interesting variables for you are the ones that | |
| 180 exist for the sake of customization. Emacs does not (usually) change the | |
| 181 values of these variables; instead, you set the values, and thereby alter | |
| 182 and control the behavior of certain Emacs commands. These variables are | |
| 183 called @dfn{options}. Most options are documented in this manual and | |
| 184 appear in the Variable Index (@pxref{Variable Index}). | |
| 185 | |
| 186 One example of a variable which is an option is @code{fill-column}, which | |
| 187 specifies the position of the right margin (as a number of characters from | |
| 188 the left margin) to be used by the fill commands (@pxref{Filling}). | |
| 189 | |
| 190 @menu | |
| 191 * Examining:: Examining or setting one variable's value. | |
| 192 * Easy Customization:: Convenient and easy customization of variables. | |
| 193 * Edit Options:: Examining or editing list of all variables' values. | |
| 194 * Locals:: Per-buffer values of variables. | |
| 195 * File Variables:: How files can specify variable values. | |
| 196 @end menu | |
| 197 | |
| 198 @node Examining | |
| 199 @subsection Examining and Setting Variables | |
| 200 @cindex setting variables | |
| 201 | |
| 202 @table @kbd | |
| 203 @item C-h v | |
| 204 @itemx M-x describe-variable | |
| 205 Print the value and documentation of a variable. | |
| 206 @findex set-variable | |
| 207 @item M-x set-variable | |
| 208 Change the value of a variable. | |
| 209 @end table | |
| 210 | |
| 211 @kindex C-h v | |
| 212 @findex describe-variable | |
| 213 To examine the value of a single variable, use @kbd{C-h v} | |
| 214 (@code{describe-variable}), which reads a variable name using the | |
| 215 minibuffer, with completion. It prints both the value and the | |
| 216 documentation of the variable. | |
| 217 | |
| 218 @example | |
| 219 C-h v fill-column @key{RET} | |
| 220 @end example | |
| 221 | |
| 222 @noindent | |
| 223 prints something like: | |
| 224 | |
| 225 @smallexample | |
| 226 fill-column's value is 75 | |
| 227 | |
| 228 Documentation: | |
| 229 *Column beyond which automatic line-wrapping should happen. | |
| 230 Automatically becomes local when set in any fashion. | |
| 231 @end smallexample | |
| 232 | |
| 233 @cindex option | |
| 234 @noindent | |
| 235 The star at the beginning of the documentation indicates that this variable | |
| 236 is an option. @kbd{C-h v} is not restricted to options; it allows any | |
| 237 variable name. | |
| 238 | |
| 239 @findex set-variable | |
| 240 If you know which option you want to set, you can use @kbd{M-x | |
| 241 set-variable} to set it. This prompts for the variable name in the | |
| 242 minibuffer (with completion), and then prompts for a Lisp expression for the | |
| 243 new value using the minibuffer a second time. For example, | |
| 244 | |
| 245 @example | |
| 246 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
| 247 @end example | |
| 248 | |
| 249 @noindent | |
| 250 sets @code{fill-column} to 75, as if you had executed the Lisp expression | |
| 251 @code{(setq fill-column 75)}. | |
| 252 | |
| 253 Setting variables in this way, like all means of customizing Emacs | |
| 254 except where explicitly stated, affects only the current Emacs session. | |
| 255 | |
| 256 @node Easy Customization | |
| 257 @subsection Easy Customization Interface | |
| 258 | |
| 259 @findex customize | |
| 260 @cindex customization buffer | |
| 261 A convenient way to find the user option variables that you want to | |
| 600 | 262 change, and then change them, is with @kbd{C-h C} (@code{customize}). |
| 263 This command creates a @dfn{customization buffer} with which you can | |
| 264 browse through the Emacs user options in a logically organized | |
| 265 structure, then edit and set their values. You can also use the | |
| 266 customization buffer to save settings permanently. (Not all Emacs user | |
| 267 options are included in this structure as of yet, but we are adding the | |
| 268 rest.) | |
| 428 | 269 |
| 270 @menu | |
| 271 * Groups: Customization Groups. | |
| 272 How options are classified in a structure. | |
| 273 * Changing an Option:: How to edit a value and set an option. | |
| 274 * Face Customization:: How to edit the attributes of a face. | |
| 275 * Specific Customization:: Making a customization buffer for specific | |
| 276 options, faces, or groups. | |
| 277 @end menu | |
| 278 | |
| 279 @node Customization Groups | |
| 280 @subsubsection Customization Groups | |
| 281 @cindex customization groups | |
| 282 | |
| 283 For customization purposes, user options are organized into | |
| 284 @dfn{groups} to help you find them. Groups are collected into bigger | |
| 285 groups, all the way up to a master group called @code{Emacs}. | |
| 286 | |
| 602 | 287 @kbd{C-h C} (@code{customize}) creates a customization buffer that |
| 600 | 288 shows the top-level @code{Emacs} group and the second-level groups |
| 289 immediately under it. It looks like this, in part: | |
| 428 | 290 |
| 291 @smallexample | |
| 292 /- Emacs group: ---------------------------------------------------\ | |
| 293 [State]: visible group members are all at standard settings. | |
| 294 Customization of the One True Editor. | |
| 295 See also [Manual]. | |
| 296 | |
| 297 [Open] Editing group | |
| 298 Basic text editing facilities. | |
| 299 | |
| 300 [Open] External group | |
| 301 Interfacing to external utilities. | |
| 302 | |
| 303 @var{more second-level groups} | |
| 304 | |
| 305 \- Emacs group end ------------------------------------------------/ | |
| 306 | |
| 307 @end smallexample | |
| 308 | |
| 309 @noindent | |
| 310 This says that the buffer displays the contents of the @code{Emacs} | |
| 311 group. The other groups are listed because they are its contents. But | |
| 312 they are listed differently, without indentation and dashes, because | |
| 313 @emph{their} contents are not included. Each group has a single-line | |
| 314 documentation string; the @code{Emacs} group also has a @samp{[State]} | |
| 315 line. | |
| 316 | |
| 317 @cindex editable fields (customization buffer) | |
| 318 @cindex active fields (customization buffer) | |
| 319 Most of the text in the customization buffer is read-only, but it | |
| 320 typically includes some @dfn{editable fields} that you can edit. There | |
| 321 are also @dfn{active fields}; this means a field that does something | |
| 322 when you @dfn{invoke} it. To invoke an active field, either click on it | |
| 323 with @kbd{Mouse-1}, or move point to it and type @key{RET}. | |
| 324 | |
| 325 For example, the phrase @samp{[Open]} that appears in a second-level | |
| 326 group is an active field. Invoking the @samp{[Open]} field for a group | |
| 327 opens up a new customization buffer, which shows that group and its | |
| 328 contents. This field is a kind of hypertext link to another group. | |
| 329 | |
| 330 The @code{Emacs} group does not include any user options itself, but | |
| 331 other groups do. By examining various groups, you will eventually find | |
| 332 the options and faces that belong to the feature you are interested in | |
| 333 customizing. Then you can use the customization buffer to set them. | |
| 334 | |
| 335 @findex customize-browse | |
| 336 You can view the structure of customization groups on a larger scale | |
| 337 with @kbd{M-x customize-browse}. This command creates a special kind of | |
| 338 customization buffer which shows only the names of the groups (and | |
| 339 options and faces), and their structure. | |
| 340 | |
| 341 In this buffer, you can show the contents of a group by invoking | |
| 342 @samp{[+]}. When the group contents are visible, this button changes to | |
| 343 @samp{[-]}; invoking that hides the group contents. | |
| 344 | |
| 345 Each group, option or face name in this buffer has an active field | |
| 346 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking | |
| 347 that active field creates an ordinary customization buffer showing just | |
| 348 that group and its contents, just that option, or just that face. | |
| 349 This is the way to set values in it. | |
| 350 | |
| 351 @node Changing an Option | |
| 352 @subsubsection Changing an Option | |
| 353 | |
| 354 Here is an example of what a user option looks like in the | |
| 355 customization buffer: | |
| 356 | |
| 357 @smallexample | |
| 358 Kill Ring Max: [Hide] 30 | |
| 359 [State]: this option is unchanged from its standard setting. | |
| 360 Maximum length of kill ring before oldest elements are thrown away. | |
| 361 @end smallexample | |
| 362 | |
| 363 The text following @samp{[Hide]}, @samp{30} in this case, indicates | |
| 364 the current value of the option. If you see @samp{[Show]} instead of | |
| 365 @samp{[Hide]}, it means that the value is hidden; the customization | |
| 366 buffer initially hides values that take up several lines. Invoke | |
| 367 @samp{[Show]} to show the value. | |
| 368 | |
| 369 The line after the option name indicates the @dfn{customization state} | |
| 370 of the option: in the example above, it says you have not changed the | |
| 371 option yet. The word @samp{[State]} at the beginning of this line is | |
| 372 active; you can get a menu of various operations by invoking it with | |
| 373 @kbd{Mouse-1} or @key{RET}. These operations are essential for | |
| 374 customizing the variable. | |
| 375 | |
| 376 The line after the @samp{[State]} line displays the beginning of the | |
| 377 option's documentation string. If there are more lines of | |
| 378 documentation, this line ends with @samp{[More]}; invoke this to show | |
| 379 the full documentation string. | |
| 380 | |
| 381 To enter a new value for @samp{Kill Ring Max}, move point to the value | |
| 382 and edit it textually. For example, you can type @kbd{M-d}, then insert | |
| 383 another number. | |
| 384 | |
| 385 When you begin to alter the text, you will see the @samp{[State]} line | |
| 386 change to say that you have edited the value: | |
| 387 | |
| 388 @smallexample | |
| 389 [State]: you have edited the value as text, but not set the option. | |
| 390 @end smallexample | |
| 391 | |
| 392 @cindex setting option value | |
| 393 Editing the value does not actually set the option variable. To do | |
| 394 that, you must @dfn{set} the option. To do this, invoke the word | |
| 395 @samp{[State]} and choose @samp{Set for Current Session}. | |
| 396 | |
| 397 The state of the option changes visibly when you set it: | |
| 398 | |
| 399 @smallexample | |
| 400 [State]: you have set this option, but not saved it for future sessions. | |
| 401 @end smallexample | |
| 402 | |
| 403 You don't have to worry about specifying a value that is not valid; | |
| 404 setting the option checks for validity and will not really install an | |
| 405 unacceptable value. | |
| 406 | |
| 407 @kindex M-TAB @r{(customization buffer)} | |
| 408 @findex widget-complete | |
| 409 While editing a value or field that is a file name, directory name, | |
| 410 command name, or anything else for which completion is defined, you can | |
| 411 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. | |
| 412 | |
| 413 Some options have a small fixed set of possible legitimate values. | |
| 414 These options don't let you edit the value textually. Instead, an | |
| 415 active field @samp{[Value Menu]} appears before the value; invoke this | |
| 416 field to edit the value. For a boolean ``on or off'' value, the active | |
| 417 field says @samp{[Toggle]}, and it changes to the other value. | |
| 418 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes | |
| 419 take effect when you use the @samp{Set for Current Session} operation. | |
| 420 | |
| 421 Some options have values with complex structure. For example, the | |
| 422 value of @code{load-path} is a list of directories. Here is how it | |
| 423 appears in the customization buffer: | |
| 424 | |
| 425 @smallexample | |
| 426 Load Path: | |
| 427 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp | |
| 428 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp | |
| 429 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim | |
| 430 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp | |
| 431 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp | |
| 432 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus | |
| 433 [INS] | |
| 434 [State]: this item has been changed outside the customization buffer. | |
| 435 List of directories to search for files to load.... | |
| 436 @end smallexample | |
| 437 | |
| 438 @noindent | |
| 439 Each directory in the list appears on a separate line, and each line has | |
| 440 several editable or active fields. | |
| 441 | |
| 442 You can edit any of the directory names. To delete a directory from | |
| 443 the list, invoke @samp{[DEL]} on that line. To insert a new directory in | |
| 444 the list, invoke @samp{[INS]} at the point where you want to insert it. | |
| 445 | |
| 446 You can also invoke @samp{[Current dir?]} to switch between including | |
| 447 a specific named directory in the path, and including @code{nil} in the | |
| 448 path. (@code{nil} in a search path means ``try the current | |
| 449 directory.'') | |
| 450 | |
| 451 @kindex TAB @r{(customization buffer)} | |
| 452 @kindex S-TAB @r{(customization buffer)} | |
| 453 @findex widget-forward | |
| 454 @findex widget-backward | |
| 455 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for | |
| 456 moving through the customization buffer. @key{TAB} | |
| 457 (@code{widget-forward}) moves forward to the next active or editable | |
| 458 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the | |
| 459 previous active or editable field. | |
| 460 | |
| 461 Typing @key{RET} on an editable field also moves forward, just like | |
| 462 @key{TAB}. The reason for this is that people have a tendency to type | |
| 463 @key{RET} when they are finished editing a field. If you have occasion | |
| 464 to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q | |
| 465 C-j}, | |
| 466 | |
| 467 @cindex saving option value | |
| 468 Setting the option changes its value in the current Emacs session; | |
| 469 @dfn{saving} the value changes it for future sessions as well. This | |
| 442 | 470 works by writing code into your init file so as to set the option |
| 471 variable again each time you start Emacs. @xref{Init File}. To save | |
| 472 the option, invoke @samp{[State]} and select the @samp{Save for Future | |
| 473 Sessions} operation. | |
| 428 | 474 |
| 475 You can also restore the option to its standard value by invoking | |
| 476 @samp{[State]} and selecting the @samp{Reset} operation. There are | |
| 477 actually three reset operations: | |
| 478 | |
| 479 @table @samp | |
| 480 @item Reset to Current | |
| 481 If you have made some modifications and not yet set the option, | |
| 482 this restores the text in the customization buffer to match | |
| 483 the actual value. | |
| 484 | |
| 485 @item Reset to Saved | |
| 486 This restores the value of the option to the last saved value, | |
| 487 and updates the text accordingly. | |
| 488 | |
| 489 @item Reset to Standard Settings | |
| 490 This sets the option to its standard value, and updates the text | |
| 491 accordingly. This also eliminates any saved value for the option, | |
| 492 so that you will get the standard value in future Emacs sessions. | |
| 493 @end table | |
| 494 | |
| 495 The state of a group indicates whether anything in that group has been | |
| 496 edited, set or saved. You can select @samp{Set for Current Session}, | |
| 497 @samp{Save for Future Sessions} and the various kinds of @samp{Reset} | |
| 498 operation for the group; these operations on the group apply to all | |
| 499 options in the group and its subgroups. | |
| 500 | |
| 501 Near the top of the customization buffer there are two lines | |
| 502 containing several active fields: | |
| 503 | |
| 504 @smallexample | |
| 505 [Set] [Save] [Reset] [Done] | |
| 506 @end smallexample | |
| 507 | |
| 508 @noindent | |
| 509 Invoking @samp{[Done]} buries this customization buffer. Each of the | |
| 510 other fields performs an operation---set, save or reset---on each of the | |
| 511 items in the buffer that could meaningfully be set, saved or reset. | |
| 512 | |
| 513 @node Face Customization | |
| 514 @subsubsection Customizing Faces | |
| 515 @cindex customizing faces | |
| 516 @cindex bold font | |
| 517 @cindex italic font | |
| 518 @cindex fonts and faces | |
| 519 | |
| 520 In addition to user options, some customization groups also include | |
| 521 faces. When you show the contents of a group, both the user options and | |
| 522 the faces in the group appear in the customization buffer. Here is an | |
| 523 example of how a face looks: | |
| 524 | |
| 525 @smallexample | |
| 526 Custom Changed Face: (sample) | |
| 527 [State]: this face is unchanged from its standard setting. | |
| 528 Face used when the customize item has been changed. | |
| 529 Parent groups: [Custom Magic Faces] | |
| 530 Attributes: [ ] Bold: [Toggle] off (nil) | |
| 531 [ ] Italic: [Toggle] off (nil) | |
| 532 [ ] Underline: [Toggle] off (nil) | |
| 533 [ ] Foreground: white (sample) | |
| 534 [ ] Background: blue (sample) | |
| 535 [ ] Inverse: [Toggle] off (nil) | |
| 1137 | 536 [ ] Stipple: |
| 537 [ ] Font Family: | |
| 538 [ ] Size: | |
| 428 | 539 [ ] Strikethru: off |
| 540 @end smallexample | |
| 541 | |
| 542 Each face attribute has its own line. The @samp{[@var{x}]} field | |
| 543 before the attribute name indicates whether the attribute is | |
| 544 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the | |
| 545 attribute by invoking that field. When the attribute is enabled, you | |
| 546 can change the attribute value in the usual ways. | |
| 547 | |
| 1142 | 548 @xref{Faces}, for description of how @code{face-frob-from-locale-first} |
| 549 variable affects changing @samp{Bold} and @samp{Italic} attributes. | |
| 550 | |
| 428 | 551 @c Is this true for XEmacs? |
| 552 @c On a black-and-white display, the colors you can use for the | |
| 553 @c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, | |
| 554 @c and @samp{gray3}. Emacs supports these shades of gray by using | |
| 555 @c background stipple patterns instead of a color. | |
| 1137 | 556 @c |
| 428 | 557 Setting, saving and resetting a face work like the same operations for |
| 558 options (@pxref{Changing an Option}). | |
| 559 | |
| 560 A face can specify different appearances for different types of | |
| 561 display. For example, a face can make text red on a color display, but | |
| 562 use a bold font on a monochrome display. To specify multiple | |
| 563 appearances for a face, select @samp{Show Display Types} in the menu you | |
| 564 get from invoking @samp{[State]}. | |
| 565 | |
| 566 @c It would be cool to implement this | |
| 567 @c @findex modify-face | |
| 568 @c Another more basic way to set the attributes of a specific face is | |
| 569 @c with @kbd{M-x modify-face}. This command reads the name of a face, then | |
| 570 @c reads the attributes one by one. For the color and stipple attributes, | |
| 571 @c the attribute's current value is the default---type just @key{RET} if | |
| 572 @c you don't want to change that attribute. Type @samp{none} if you want | |
| 573 @c to clear out the attribute. | |
| 574 | |
| 575 @node Specific Customization | |
| 576 @subsubsection Customizing Specific Items | |
| 577 | |
| 578 Instead of finding the options you want to change by moving down | |
| 579 through the structure of groups, you can specify the particular option, | |
| 580 face or group that you want to customize. | |
| 581 | |
| 582 @table @kbd | |
| 583 @item M-x customize-option @key{RET} @var{option} @key{RET} | |
| 584 Set up a customization buffer with just one option, @var{option}. | |
| 585 @item M-x customize-face @key{RET} @var{face} @key{RET} | |
| 586 Set up a customization buffer with just one face, @var{face}. | |
| 587 @item M-x customize-group @key{RET} @var{group} @key{RET} | |
| 588 Set up a customization buffer with just one group, @var{group}. | |
| 589 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET} | |
| 590 Set up a customization buffer with all the options, faces and groups | |
| 591 that match @var{regexp}. | |
| 1137 | 592 @item M-x customize-saved |
| 428 | 593 Set up a customization buffer containing all options and faces that you |
| 594 have saved with customization buffers. | |
| 595 @item M-x customize-customized | |
| 596 Set up a customization buffer containing all options and faces that you | |
| 597 have customized but not saved. | |
| 598 @end table | |
| 599 | |
| 600 @findex customize-option | |
| 601 If you want to alter a particular user option variable with the | |
| 602 customization buffer, and you know its name, you can use the command | |
| 603 @kbd{M-x customize-option} and specify the option name. This sets up | |
| 604 the customization buffer with just one option---the one that you asked | |
| 605 for. Editing, setting and saving the value work as described above, but | |
| 606 only for the specified option. | |
| 607 | |
| 608 @findex customize-face | |
| 609 Likewise, you can modify a specific face, chosen by name, using | |
| 610 @kbd{M-x customize-face}. | |
| 611 | |
| 612 @findex customize-group | |
| 613 You can also set up the customization buffer with a specific group, | |
| 614 using @kbd{M-x customize-group}. The immediate contents of the chosen | |
| 615 group, including option variables, faces, and other groups, all appear | |
| 616 as well. However, these subgroups' own contents start out hidden. You | |
| 617 can show their contents in the usual way, by invoking @samp{[Show]}. | |
| 618 | |
| 619 @findex customize-apropos | |
| 620 To control more precisely what to customize, you can use @kbd{M-x | |
| 621 customize-apropos}. You specify a regular expression as argument; then | |
| 622 all options, faces and groups whose names match this regular expression | |
| 623 are set up in the customization buffer. If you specify an empty regular | |
| 624 expression, this includes @emph{all} groups, options and faces in the | |
| 625 customization buffer (but that takes a long time). | |
| 626 | |
| 627 @findex customize-saved | |
| 628 @findex customize-customized | |
| 629 If you change option values and then decide the change was a mistake, | |
| 630 you can use two special commands to revisit your previous changes. Use | |
| 631 @kbd{customize-saved} to look at the options and faces that you have | |
| 632 saved. Use @kbd{M-x customize-customized} to look at the options and | |
| 633 faces that you have set but not saved. | |
| 634 | |
| 635 @node Edit Options | |
| 636 @subsection Editing Variable Values | |
| 637 | |
| 638 @table @kbd | |
| 639 @item M-x list-options | |
| 640 Display a buffer listing names, values, and documentation of all options. | |
| 641 @item M-x edit-options | |
| 642 Change option values by editing a list of options. | |
| 643 @end table | |
| 644 | |
| 645 @findex list-options | |
| 646 @kbd{M-x list-options} displays a list of all Emacs option variables in | |
| 647 an Emacs buffer named @samp{*List Options*}. Each option is shown with its | |
| 648 documentation and its current value. Here is what a portion of it might | |
| 649 look like: | |
| 650 | |
| 651 @smallexample | |
| 652 ;; exec-path: | |
| 653 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") | |
| 654 *List of directories to search programs to run in subprocesses. | |
| 655 Each element is a string (directory name) | |
| 656 or nil (try the default directory). | |
| 657 ;; | |
| 658 ;; fill-column: | |
| 659 75 | |
| 660 *Column beyond which automatic line-wrapping should happen. | |
| 661 Automatically becomes local when set in any fashion. | |
| 662 ;; | |
| 663 @end smallexample | |
| 664 | |
| 665 @findex edit-options | |
| 666 @kbd{M-x edit-options} goes one step further and immediately selects the | |
| 667 @samp{*List Options*} buffer; this buffer uses the major mode Options mode, | |
| 668 which provides commands that allow you to point at an option and change its | |
| 669 value: | |
| 670 | |
| 671 @table @kbd | |
| 672 @item s | |
| 673 Set the variable point is in or near to a new value read using the | |
| 674 minibuffer. | |
| 675 @item x | |
| 676 Toggle the variable point is in or near: if the value was @code{nil}, | |
| 677 it becomes @code{t}; otherwise it becomes @code{nil}. | |
| 678 @item 1 | |
| 679 Set the variable point is in or near to @code{t}. | |
| 680 @item 0 | |
| 681 Set the variable point is in or near to @code{nil}. | |
| 682 @item n | |
| 683 @itemx p | |
| 684 Move to the next or previous variable. | |
| 685 @end table | |
| 686 | |
| 687 @node Locals | |
| 688 @subsection Local Variables | |
| 689 | |
| 690 @table @kbd | |
| 691 @item M-x make-local-variable | |
| 692 Make a variable have a local value in the current buffer. | |
| 693 @item M-x kill-local-variable | |
| 694 Make a variable use its global value in the current buffer. | |
| 695 @item M-x make-variable-buffer-local | |
| 696 Mark a variable so that setting it will make it local to the | |
| 697 buffer that is current at that time. | |
| 698 @end table | |
| 699 | |
| 700 @cindex local variables | |
| 701 You can make any variable @dfn{local} to a specific Emacs buffer. | |
| 702 This means that the variable's value in that buffer is independent of | |
| 703 its value in other buffers. A few variables are always local in every | |
| 704 buffer. All other Emacs variables have a @dfn{global} value which is in | |
| 705 effect in all buffers that have not made the variable local. | |
| 706 | |
| 707 Major modes always make the variables they set local to the buffer. | |
| 708 This is why changing major modes in one buffer has no effect on other | |
| 709 buffers. | |
| 710 | |
| 711 @findex make-local-variable | |
| 712 @kbd{M-x make-local-variable} reads the name of a variable and makes it | |
| 713 local to the current buffer. Further changes in this buffer will not | |
| 714 affect others, and changes in the global value will not affect this | |
| 715 buffer. | |
| 716 | |
| 717 @findex make-variable-buffer-local | |
| 718 @cindex per-buffer variables | |
| 719 @kbd{M-x make-variable-buffer-local} reads the name of a variable and | |
| 720 changes the future behavior of the variable so that it automatically | |
| 721 becomes local when it is set. More precisely, once you have marked a | |
| 722 variable in this way, the usual ways of setting the | |
| 723 variable will automatically invoke @code{make-local-variable} first. We | |
| 724 call such variables @dfn{per-buffer} variables. | |
| 725 | |
| 726 Some important variables have been marked per-buffer already. They | |
| 727 include @code{abbrev-mode}, @code{auto-fill-function}, | |
| 728 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow}, | |
| 729 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode}, | |
| 730 @code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode}, | |
| 731 @code{selective-display-ellipses}, @*@code{selective-display}, | |
| 732 @code{tab-width}, and @code{truncate-lines}. Some other variables are | |
| 733 always local in every buffer, but they are used for internal | |
| 734 purposes.@refill | |
| 735 | |
| 736 Note: the variable @code{auto-fill-function} was formerly named | |
| 737 @code{auto-fill-hook}. | |
| 738 | |
| 739 @findex kill-local-variable | |
| 740 If you want a variable to cease to be local to the current buffer, | |
| 741 call @kbd{M-x kill-local-variable} and provide the name of a variable to | |
| 742 the prompt. The global value of the variable | |
| 743 is again in effect in this buffer. Setting the major mode kills all | |
| 744 the local variables of the buffer. | |
| 745 | |
| 746 @findex setq-default | |
| 747 To set the global value of a variable, regardless of whether the | |
| 748 variable has a local value in the current buffer, you can use the | |
| 749 Lisp function @code{setq-default}. It works like @code{setq}. | |
| 750 If there is a local value in the current buffer, the local value is | |
| 751 not affected by @code{setq-default}; thus, the new global value may | |
| 752 not be visible until you switch to another buffer, as in the case of: | |
| 753 | |
| 754 @example | |
| 755 (setq-default fill-column 75) | |
| 756 @end example | |
| 757 | |
| 758 @noindent | |
| 759 @code{setq-default} is the only way to set the global value of a variable | |
| 760 that has been marked with @code{make-variable-buffer-local}. | |
| 761 | |
| 762 @findex default-value | |
| 763 Programs can look at a variable's default value with @code{default-value}. | |
| 764 This function takes a symbol as an argument and returns its default value. | |
| 765 The argument is evaluated; usually you must quote it explicitly, as in | |
| 766 the case of: | |
| 767 | |
| 768 @example | |
| 769 (default-value 'fill-column) | |
| 770 @end example | |
| 771 | |
| 772 @node File Variables | |
| 773 @subsection Local Variables in Files | |
| 774 @cindex local variables in files | |
| 775 | |
| 776 A file can contain a @dfn{local variables list}, which specifies the | |
| 3510 | 777 buffer-local values to use for certain Emacs variables when that file is |
| 778 edited. Visiting the file checks for a local variables list and makes | |
| 779 each variable in the list local to the buffer in which the file is | |
| 780 visited, with the value specified in the file. | |
| 428 | 781 |
| 782 A local variables list goes near the end of the file, in the last page. | |
| 783 (It is often best to put it on a page by itself.) The local variables list | |
| 784 starts with a line containing the string @samp{Local Variables:}, and ends | |
| 785 with a line containing the string @samp{End:}. In between come the | |
| 786 variable names and values, one set per line, as @samp{@var{variable}:@: | |
| 787 @var{value}}. The @var{value}s are not evaluated; they are used literally. | |
| 788 | |
| 789 The line which starts the local variables list does not have to say | |
| 790 just @samp{Local Variables:}. If there is other text before @samp{Local | |
| 791 Variables:}, that text is called the @dfn{prefix}, and if there is other | |
| 792 text after, that is called the @dfn{suffix}. If a prefix or suffix are | |
| 793 present, each entry in the local variables list should have the prefix | |
| 794 before it and the suffix after it. This includes the @samp{End:} line. | |
| 795 The prefix and suffix are included to disguise the local variables list | |
| 796 as a comment so the compiler or text formatter will ignore it. | |
| 797 If you do not need to disguise the local variables list as a comment in | |
| 798 this way, there is no need to include a prefix or a suffix.@refill | |
| 799 | |
| 800 Two ``variable'' names are special in a local variables list: a value | |
| 801 for the variable @code{mode} sets the major mode, and a value for the | |
| 802 variable @code{eval} is simply evaluated as an expression and the value | |
| 803 is ignored. These are not real variables; setting them in any other | |
| 804 context does not have the same effect. If @code{mode} is used in a | |
| 805 local variables list, it should be the first entry in the list. | |
| 806 | |
| 807 Here is an example of a local variables list: | |
| 808 @example | |
| 809 ;;; Local Variables: *** | |
| 810 ;;; mode:lisp *** | |
| 811 ;;; comment-column:0 *** | |
| 812 ;;; comment-start: ";;; " *** | |
| 813 ;;; comment-end:"***" *** | |
| 814 ;;; End: *** | |
| 815 @end example | |
| 816 | |
| 817 Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}. | |
| 818 Note also that comments in the file begin with and end with the same | |
| 819 strings. Presumably the file contains code in a language which is | |
| 820 enough like Lisp for Lisp mode to be useful but in which comments | |
| 821 start and end differently. The prefix and suffix are used in the local | |
| 822 variables list to make the list look like several lines of comments when | |
| 1137 | 823 the compiler or interpreter for that language reads the file. |
| 428 | 824 |
| 825 The start of the local variables list must be no more than 3000 | |
| 826 characters from the end of the file, and must be in the last page if the | |
| 827 file is divided into pages. Otherwise, Emacs will not notice it is | |
| 828 there. The purpose is twofold: a stray @samp{Local Variables:}@: not in | |
| 829 the last page does not confuse Emacs, and Emacs never needs to search a | |
| 830 long file that contains no page markers and has no local variables list. | |
| 831 | |
| 2736 | 832 You may be tempted to turn on minor modes like Auto Fill mode with a |
| 833 local variable list. That is inappropriate. Those behaviors that seem | |
| 834 appropriate for almost any personal taste, such as setting up the syntax | |
| 835 table "symbol constituent" character class, are collected into a major | |
| 836 mode. But whether you use Auto Fill mode or not is | |
| 428 | 837 a matter of personal taste, not a matter of the contents of particular |
| 838 files. If you want to use Auto Fill, set up major mode hooks with your | |
| 442 | 839 init file to turn it on (when appropriate) for you alone |
| 2736 | 840 (@pxref{Init File}). Don't use a local variable list that would |
| 428 | 841 impose your taste on everyone working with the file. |
| 842 | |
| 843 XEmacs allows you to specify local variables in the first line | |
| 844 of a file, in addition to specifying them in the @code{Local Variables} | |
| 845 section at the end of a file. | |
| 846 | |
| 847 If the first line of a file contains two occurrences of @code{`-*-'}, | |
| 848 XEmacs uses the information between them to determine what the major | |
| 849 mode and variable settings should be. For example, these are all legal: | |
| 850 | |
| 851 @example | |
| 440 | 852 ;;; -*- mode: emacs-lisp -*- |
| 853 ;;; -*- mode: postscript; version-control: never -*- | |
| 854 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*- | |
| 428 | 855 @end example |
| 856 | |
| 857 For historical reasons, the syntax @code{`-*- modename -*-'} is allowed | |
| 858 as well; for example, you can use: | |
| 859 | |
| 860 @example | |
| 440 | 861 ;;; -*- emacs-lisp -*- |
| 428 | 862 @end example |
| 863 | |
| 864 @vindex enable-local-variables | |
| 865 The variable @code{enable-local-variables} controls the use of local | |
| 866 variables lists in files you visit. The value can be @code{t}, | |
| 867 @code{nil}, or something else. A value of @code{t} means local variables | |
| 868 lists are obeyed; @code{nil} means they are ignored; anything else means | |
| 869 query. | |
| 870 | |
| 871 The command @code{M-x normal-mode} always obeys local variables lists | |
| 872 and ignores this variable. | |
| 873 | |
| 874 @node Keyboard Macros | |
| 875 @section Keyboard Macros | |
| 876 | |
| 877 @cindex keyboard macros | |
| 878 A @dfn{keyboard macro} is a command defined by the user to abbreviate a | |
| 879 sequence of keys. For example, if you discover that you are about to type | |
| 880 @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard | |
| 881 macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty. | |
| 882 | |
| 883 @c widecommands | |
| 884 @table @kbd | |
| 885 @item C-x ( | |
| 886 Start defining a keyboard macro (@code{start-kbd-macro}). | |
| 887 @item C-x ) | |
| 888 End the definition of a keyboard macro (@code{end-kbd-macro}). | |
| 889 @item C-x e | |
| 890 Execute the most recent keyboard macro (@code{call-last-kbd-macro}). | |
| 891 @item C-u C-x ( | |
| 892 Re-execute last keyboard macro, then add more keys to its definition. | |
| 893 @item C-x q | |
| 894 When this point is reached during macro execution, ask for confirmation | |
| 895 (@code{kbd-macro-query}). | |
| 896 @item M-x name-last-kbd-macro | |
| 897 Give a command name (for the duration of the session) to the most | |
| 898 recently defined keyboard macro. | |
| 899 @item M-x insert-kbd-macro | |
| 900 Insert in the buffer a keyboard macro's definition, as Lisp code. | |
| 901 @end table | |
| 902 | |
| 903 Keyboard macros differ from other Emacs commands in that they are | |
| 904 written in the Emacs command language rather than in Lisp. This makes it | |
| 905 easier for the novice to write them and makes them more convenient as | |
| 906 temporary hacks. However, the Emacs command language is not powerful | |
| 907 enough as a programming language to be useful for writing anything | |
| 908 general or complex. For such things, Lisp must be used. | |
| 909 | |
| 910 You define a keyboard macro by executing the commands which are its | |
| 911 definition. Put differently, as you are defining a keyboard macro, the | |
| 912 definition is being executed for the first time. This way, you see | |
| 913 what the effects of your commands are, and don't have to figure | |
| 914 them out in your head. When you are finished, the keyboard macro is | |
| 915 defined and also has been executed once. You can then execute the same | |
| 916 set of commands again by invoking the macro. | |
| 917 | |
| 918 @menu | |
| 919 * Basic Kbd Macro:: Defining and running keyboard macros. | |
| 920 * Save Kbd Macro:: Giving keyboard macros names; saving them in files. | |
| 921 * Kbd Macro Query:: Keyboard macros that do different things each use. | |
| 922 @end menu | |
| 923 | |
| 924 @node Basic Kbd Macro | |
| 925 @subsection Basic Use | |
| 926 | |
| 927 @kindex C-x ( | |
| 928 @kindex C-x ) | |
| 929 @kindex C-x e | |
| 930 @findex start-kbd-macro | |
| 931 @findex end-kbd-macro | |
| 932 @findex call-last-kbd-macro | |
| 933 To start defining a keyboard macro, type @kbd{C-x (} | |
| 934 (@code{start-kbd-macro}). From then on, anything you type continues to be | |
| 935 executed, but also becomes part of the definition of the macro. @samp{Def} | |
| 936 appears in the mode line to remind you of what is going on. When you are | |
| 937 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the | |
| 1137 | 938 definition, without becoming part of it. |
| 428 | 939 |
| 940 For example, | |
| 941 | |
| 942 @example | |
| 943 C-x ( M-f foo C-x ) | |
| 944 @end example | |
| 945 | |
| 946 @noindent | |
| 947 defines a macro to move forward a word and then insert @samp{foo}. | |
| 948 | |
| 949 You can give @kbd{C-x )} a repeat count as an argument, in which case it | |
| 950 repeats the macro that many times right after defining it, but defining | |
| 951 the macro counts as the first repetition (since it is executed as you | |
| 952 define it). If you give @kbd{C-x )} an argument of 4, it executes the | |
| 953 macro immediately 3 additional times. An argument of zero to @kbd{C-x | |
| 954 e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an | |
| 955 error or you type @kbd{C-g}). | |
| 956 | |
| 957 Once you have defined a macro, you can invoke it again with the | |
| 958 @kbd{C-x e} command (@code{call-last-kbd-macro}). You can give the | |
| 959 command a repeat count numeric argument to execute the macro many times. | |
| 960 | |
| 961 To repeat an operation at regularly spaced places in the | |
| 962 text, define a macro and include as part of the macro the commands to move | |
| 963 to the next place you want to use it. For example, if you want to change | |
| 964 each line, you should position point at the start of a line, and define a | |
| 965 macro to change that line and leave point at the start of the next line. | |
| 966 Repeating the macro will then operate on successive lines. | |
| 967 | |
| 968 After you have terminated the definition of a keyboard macro, you can add | |
| 969 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent | |
| 970 to plain @kbd{C-x (} followed by retyping the whole definition so far. As | |
| 971 a consequence it re-executes the macro as previously defined. | |
| 972 | |
| 973 @node Save Kbd Macro | |
| 974 @subsection Naming and Saving Keyboard Macros | |
| 975 | |
| 976 @findex name-last-kbd-macro | |
| 977 To save a keyboard macro for longer than until you define the | |
| 978 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. | |
| 979 This reads a name as an argument using the minibuffer and defines that name | |
| 980 to execute the macro. The macro name is a Lisp symbol, and defining it in | |
| 981 this way makes it a valid command name for calling with @kbd{M-x} or for | |
| 982 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you | |
| 983 specify a name that has a prior definition other than another keyboard | |
| 984 macro, Emacs prints an error message and nothing is changed. | |
| 985 | |
| 986 @findex insert-kbd-macro | |
| 987 Once a macro has a command name, you can save its definition in a file. | |
| 988 You can then use it in another editing session. First visit the file | |
| 989 you want to save the definition in. Then use the command: | |
| 990 | |
| 991 @example | |
| 992 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} | |
| 993 @end example | |
| 994 | |
| 995 @noindent | |
| 996 This inserts some Lisp code that, when executed later, will define the same | |
| 997 macro with the same definition it has now. You need not understand Lisp | |
| 998 code to do this, because @code{insert-kbd-macro} writes the Lisp code for you. | |
| 999 Then save the file. You can load the file with @code{load-file} | |
| 1000 (@pxref{Lisp Libraries}). If the file you save in is your initialization file | |
| 442 | 1001 (@pxref{Init File}), then the macro will be defined each |
| 428 | 1002 time you run Emacs. |
| 1003 | |
| 1004 If you give @code{insert-kbd-macro} a prefix argument, it creates | |
| 1005 additional Lisp code to record the keys (if any) that you have bound to the | |
| 1006 keyboard macro, so that the macro is reassigned the same keys when you | |
| 1007 load the file. | |
| 1008 | |
| 1009 @node Kbd Macro Query | |
| 1010 @subsection Executing Macros With Variations | |
| 1011 | |
| 1012 @kindex C-x q | |
| 1013 @findex kbd-macro-query | |
| 1014 You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar | |
| 1015 to that of @code{query-replace}. The macro asks you each time | |
| 1016 whether to make a change. When you are defining the macro, type @kbd{C-x | |
| 1017 q} at the point where you want the query to occur. During macro | |
| 1018 definition, the @kbd{C-x q} does nothing, but when you invoke the macro, | |
| 1019 @kbd{C-x q} reads a character from the terminal to decide whether to | |
| 1020 continue. | |
| 1021 | |
| 1022 The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL}, | |
| 1023 @kbd{C-d}, @kbd{C-l}, and @kbd{C-r}. Any other character terminates | |
| 1024 execution of the keyboard macro and is then read as a command. | |
| 1025 @key{SPC} means to continue. @key{DEL} means to skip the remainder of | |
| 1026 this repetition of the macro, starting again from the beginning in the | |
| 1027 next repetition. @kbd{C-d} means to skip the remainder of this | |
| 1028 repetition and cancel further repetition. @kbd{C-l} redraws the frame | |
| 1029 and asks you again for a character to specify what to do. @kbd{C-r} enters | |
| 1030 a recursive editing level, in which you can perform editing that is not | |
| 1031 part of the macro. When you exit the recursive edit using @kbd{C-M-c}, | |
| 1032 you are asked again how to continue with the keyboard macro. If you | |
| 1033 type a @key{SPC} at this time, the rest of the macro definition is | |
| 1034 executed. It is up to you to leave point and the text in a state such | |
| 1035 that the rest of the macro will do what you want.@refill | |
| 1036 | |
| 1037 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a | |
| 1038 different function. It enters a recursive edit reading input from the | |
| 1039 keyboard, both when you type it during the definition of the macro and | |
| 1040 when it is executed from the macro. During definition, the editing you do | |
| 1041 inside the recursive edit does not become part of the macro. During macro | |
| 1042 execution, the recursive edit gives you a chance to do some particularized | |
| 1043 editing. @xref{Recursive Edit}. | |
| 1044 | |
| 1045 @node Key Bindings | |
| 1046 @section Customizing Key Bindings | |
| 1047 | |
| 1048 This section deals with the @dfn{keymaps} that define the bindings | |
| 1049 between keys and functions, and shows how you can customize these bindings. | |
| 1050 @cindex command | |
| 1051 @cindex function | |
| 1052 @cindex command name | |
| 1053 | |
| 1054 A command is a Lisp function whose definition provides for interactive | |
| 1055 use. Like every Lisp function, a command has a function name, which is | |
| 1056 a Lisp symbol whose name usually consists of lower case letters and | |
| 1057 hyphens. | |
| 1058 | |
| 1059 @menu | |
| 1060 * Keymaps:: Definition of the keymap data structure. | |
| 1061 Names of Emacs's standard keymaps. | |
| 1062 * Rebinding:: How to redefine one key's meaning conveniently. | |
| 1063 * Disabling:: Disabling a command means confirmation is required | |
| 1064 before it can be executed. This is done to protect | |
| 1065 beginners from surprises. | |
| 1066 @end menu | |
| 1067 | |
| 1068 @node Keymaps | |
| 1069 @subsection Keymaps | |
| 1070 @cindex keymap | |
| 1071 | |
| 1072 @cindex global keymap | |
| 1073 @vindex global-map | |
| 1074 The bindings between characters and command functions are recorded in | |
| 1075 data structures called @dfn{keymaps}. Emacs has many of these. One, the | |
| 1076 @dfn{global} keymap, defines the meanings of the single-character keys that | |
| 1077 are defined regardless of major mode. It is the value of the variable | |
| 1078 @code{global-map}. | |
| 1079 | |
| 1080 @cindex local keymap | |
| 1081 @vindex c-mode-map | |
| 1082 @vindex lisp-mode-map | |
| 1083 Each major mode has another keymap, its @dfn{local keymap}, which | |
| 1084 contains overriding definitions for the single-character keys that are | |
| 1085 redefined in that mode. Each buffer records which local keymap is | |
| 1086 installed for it at any time, and the current buffer's local keymap is | |
| 1087 the only one that directly affects command execution. The local keymaps | |
| 1088 for Lisp mode, C mode, and many other major modes always exist even when | |
| 1089 not in use. They are the values of the variables @code{lisp-mode-map}, | |
| 1090 @code{c-mode-map}, and so on. For less frequently used major modes, the | |
| 1091 local keymap is sometimes constructed only when the mode is used for the | |
| 1092 first time in a session, to save space. | |
| 1093 | |
| 1094 @cindex minibuffer | |
| 1095 @vindex minibuffer-local-map | |
| 1096 @vindex minibuffer-local-ns-map | |
| 1097 @vindex minibuffer-local-completion-map | |
| 1098 @vindex minibuffer-local-must-match-map | |
| 1099 @vindex repeat-complex-command-map | |
| 1100 @vindex isearch-mode-map | |
| 1101 There are local keymaps for the minibuffer, too; they contain various | |
| 1102 completion and exit commands. | |
| 1103 | |
| 1104 @itemize @bullet | |
| 1105 @item | |
| 1106 @code{minibuffer-local-map} is used for ordinary input (no completion). | |
| 1107 @item | |
| 1108 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits | |
| 1109 just like @key{RET}. This is used mainly for Mocklisp compatibility. | |
| 1110 @item | |
| 1111 @code{minibuffer-local-completion-map} is for permissive completion. | |
| 1112 @item | |
| 1113 @code{minibuffer-local-must-match-map} is for strict completion and | |
| 1114 for cautious completion. | |
| 1115 @item | |
| 1116 @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}. | |
| 1117 @item | |
| 1118 @code{isearch-mode-map} contains the bindings of the special keys which | |
| 1119 are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}. | |
| 1120 @end itemize | |
| 1121 | |
| 1122 @vindex ctl-x-map | |
| 1123 @vindex help-map | |
| 1124 @vindex esc-map | |
| 1125 Finally, each prefix key has a keymap which defines the key sequences | |
| 1126 that start with it. For example, @code{ctl-x-map} is the keymap used for | |
| 1127 characters following a @kbd{C-x}. | |
| 1128 | |
| 1129 @itemize @bullet | |
| 1130 @item | |
| 1131 @code{ctl-x-map} is the variable name for the map used for characters that | |
| 1132 follow @kbd{C-x}. | |
| 1133 @item | |
| 1134 @code{help-map} is used for characters that follow @kbd{C-h}. | |
| 1135 @item | |
| 1136 @code{esc-map} is for characters that follow @key{ESC}. All Meta | |
| 1137 characters are actually defined by this map. | |
| 1138 @item | |
| 1139 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. | |
| 1140 @item | |
| 1141 @code{mode-specific-map} is for characters that follow @kbd{C-c}. | |
| 1142 @end itemize | |
| 1143 | |
| 1144 The definition of a prefix key is the keymap to use for looking up | |
| 1145 the following character. Sometimes the definition is actually a Lisp | |
| 1146 symbol whose function definition is the following character keymap. The | |
| 1147 effect is the same, but it provides a command name for the prefix key that | |
| 1148 you can use as a description of what the prefix key is for. Thus the | |
| 1149 binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function | |
| 1150 definition is the keymap for @kbd{C-x} commands, the value of | |
| 1151 @code{ctl-x-map}.@refill | |
| 1152 | |
| 1153 Prefix key definitions can appear in either the global | |
| 1154 map or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h}, | |
| 1155 and @key{ESC} as prefix keys appear in the global map, so these prefix | |
| 1156 keys are always available. Major modes can locally redefine a key as a | |
| 1157 prefix by putting a prefix key definition for it in the local | |
| 1158 map.@refill | |
| 1159 | |
| 1160 A mode can also put a prefix definition of a global prefix character such | |
| 1161 as @kbd{C-x} into its local map. This is how major modes override the | |
| 1162 definitions of certain keys that start with @kbd{C-x}. This case is | |
| 1163 special, because the local definition does not entirely replace the global | |
| 1164 one. When both the global and local definitions of a key are other | |
| 1165 keymaps, the next character is looked up in both keymaps, with the local | |
| 1166 definition overriding the global one. The character after the | |
| 1167 @kbd{C-x} is looked up in both the major mode's own keymap for redefined | |
| 1168 @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap | |
| 1169 for @kbd{C-x} commands contains @code{nil}, the definition from the global | |
| 1170 keymap for @kbd{C-x} commands is used.@refill | |
| 1171 | |
| 1172 @node Rebinding | |
| 1173 @subsection Changing Key Bindings | |
| 1174 @cindex key rebinding, this session | |
| 1175 @cindex rebinding keys, this session | |
| 1176 | |
| 1177 You can redefine an Emacs key by changing its entry in a keymap. | |
| 1178 You can change the global keymap, in which case the change is effective in | |
| 1179 all major modes except those that have their own overriding local | |
| 1180 definitions for the same key. Or you can change the current buffer's | |
| 1181 local map, which affects all buffers using the same major mode. | |
| 1182 | |
| 1183 @menu | |
| 1137 | 1184 * Interactive Rebinding:: Changing Key Bindings Interactively |
| 438 | 1185 * Programmatic Rebinding:: Changing Key Bindings Programmatically |
| 1137 | 1186 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings |
| 428 | 1187 @end menu |
| 1188 | |
| 1189 @node Interactive Rebinding | |
| 1190 @subsubsection Changing Key Bindings Interactively | |
| 1191 @findex global-set-key | |
| 1192 @findex local-set-key | |
| 1193 @findex local-unset-key | |
| 1194 | |
| 1195 @table @kbd | |
| 1196 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} | |
| 1197 Defines @var{key} globally to run @var{cmd}. | |
| 1137 | 1198 @item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET} |
| 428 | 1199 Defines @var{key} locally (in the major mode now in effect) to run |
| 1200 @var{cmd}. | |
| 1201 @item M-x local-unset-key @key{RET} @var{keys} @key{RET} | |
| 1202 Removes the local binding of @var{key}. | |
| 1203 @end table | |
| 1204 | |
| 1205 @var{cmd} is a symbol naming an interactively-callable function. | |
| 1206 | |
| 1207 When called interactively, @var{key} is the next complete key sequence | |
| 1208 that you type. When called as a function, @var{key} is a string, a | |
| 1209 vector of events, or a vector of key-description lists as described in | |
| 1210 the @code{define-key} function description. The binding goes in | |
| 1211 the current buffer's local map, which is shared with other buffers in | |
| 1212 the same major mode. | |
| 1213 | |
| 1214 The following example: | |
| 1215 | |
| 1216 @example | |
| 1217 M-x global-set-key @key{RET} C-f next-line @key{RET} | |
| 1218 @end example | |
| 1219 | |
| 1220 @noindent | |
| 1221 redefines @kbd{C-f} to move down a line. The fact that @var{cmd} is | |
| 1222 read second makes it serve as a kind of confirmation for @var{key}. | |
| 1223 | |
| 1224 These functions offer no way to specify a particular prefix keymap as | |
| 1225 the one to redefine in, but that is not necessary, as you can include | |
| 1226 prefixes in @var{key}. @var{key} is read by reading characters one by | |
| 1227 one until they amount to a complete key (that is, not a prefix key). | |
| 1228 Thus, if you type @kbd{C-f} for @var{key}, Emacs enters | |
| 1229 the minibuffer immediately to read @var{cmd}. But if you type | |
| 1230 @kbd{C-x}, another character is read; if that character is @kbd{4}, | |
| 1231 another character is read, and so on. For example,@refill | |
| 1232 | |
| 1233 @example | |
| 1234 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} | |
| 1235 @end example | |
| 1236 | |
| 1237 @noindent | |
| 1238 redefines @kbd{C-x 4 $} to run the (fictitious) command | |
| 1239 @code{spell-other-window}. | |
| 1240 | |
| 1241 @findex define-key | |
| 1242 @findex substitute-key-definition | |
| 1243 The most general way to modify a keymap is the function | |
| 442 | 1244 @code{define-key}, used in Lisp code (such as your init file). |
| 428 | 1245 @code{define-key} takes three arguments: the keymap, the key to modify |
| 1246 in it, and the new definition. @xref{Init File}, for an example. | |
| 1247 @code{substitute-key-definition} is used similarly; it takes three | |
| 1248 arguments, an old definition, a new definition, and a keymap, and | |
| 1249 redefines in that keymap all keys that were previously defined with the | |
| 1250 old definition to have the new definition instead. | |
| 1251 | |
| 1252 @node Programmatic Rebinding | |
| 1253 @subsubsection Changing Key Bindings Programmatically | |
| 1254 | |
| 1255 You can use the functions @code{global-set-key} and @code{define-key} | |
| 1256 to rebind keys under program control. | |
| 1257 | |
| 1258 @findex define-key | |
| 1259 @findex global-set-key | |
| 1260 | |
| 1261 @table @kbd | |
| 1262 @item @code{(global-set-key @var{keys} @var{cmd})} | |
| 1263 Defines @var{keys} globally to run @var{cmd}. | |
| 1264 @item @code{(define-key @var{keymap} @var{keys} @var{def})} | |
| 1265 Defines @var{keys} to run @var{def} in the keymap @var{keymap}. | |
| 1266 @end table | |
| 1137 | 1267 |
| 428 | 1268 @var{keymap} is a keymap object. |
| 1269 | |
| 1270 @var{keys} is the sequence of keystrokes to bind. | |
| 1271 | |
| 1272 @var{def} is anything that can be a key's definition: | |
| 1273 | |
| 1274 @itemize @bullet | |
| 1275 @item | |
| 1276 @code{nil}, meaning key is undefined in this keymap | |
| 1277 @item | |
| 1278 A command, that is, a Lisp function suitable for interactive calling | |
| 1279 @item | |
| 1280 A string or key sequence vector, which is treated as a keyboard macro | |
| 1281 @item | |
| 1282 A keymap to define a prefix key | |
| 1283 @item | |
| 1284 A symbol so that when the key is looked up, the symbol stands for its | |
| 1285 function definition, which should at that time be one of the above, | |
| 1286 or another symbol whose function definition is used, and so on | |
| 1287 @item | |
| 1288 A cons, @code{(string . defn)}, meaning that @var{defn} is the definition | |
| 1289 (@var{defn} should be a valid definition in its own right) | |
| 1290 @item | |
| 1291 A cons, @code{(keymap . char)}, meaning use the definition of | |
| 1292 @var{char} in map @var{keymap} | |
| 1293 @end itemize | |
| 1294 | |
| 1295 For backward compatibility, XEmacs allows you to specify key | |
| 1296 sequences as strings. However, the preferred method is to use the | |
| 1297 representations of key sequences as vectors of keystrokes. | |
| 1298 @xref{Keystrokes}, for more information about the rules for constructing | |
| 1299 key sequences. | |
| 1300 | |
| 1137 | 1301 Emacs allows you to abbreviate representations for key sequences in |
| 428 | 1302 most places where there is no ambiguity. |
| 1303 Here are some rules for abbreviation: | |
| 1304 | |
| 1305 @itemize @bullet | |
| 1306 @item | |
| 1307 The keysym by itself is equivalent to a list of just that keysym, i.e., | |
| 1308 @code{f1} is equivalent to @code{(f1)}. | |
| 1309 @item | |
| 1310 A keystroke by itself is equivalent to a vector containing just that | |
| 1311 keystroke, i.e., @code{(control a)} is equivalent to @code{[(control a)]}. | |
| 1312 @item | |
| 1313 You can use ASCII codes for keysyms that have them. i.e., | |
| 1314 @code{65} is equivalent to @code{A}. (This is not so much an | |
| 1315 abbreviation as an alternate representation.) | |
| 1316 @end itemize | |
| 1317 | |
| 1318 Here are some examples of programmatically binding keys: | |
| 1319 | |
| 1320 @example | |
| 1321 | |
| 1322 ;;; Bind @code{my-command} to @key{f1} | |
| 1137 | 1323 (global-set-key 'f1 'my-command) |
| 428 | 1324 |
| 1325 ;;; Bind @code{my-command} to @kbd{Shift-f1} | |
| 1326 (global-set-key '(shift f1) 'my-command) | |
| 1327 | |
| 1328 ;;; Bind @code{my-command} to @kbd{C-c Shift-f1} | |
| 1137 | 1329 (global-set-key '[(control c) (shift f1)] 'my-command) |
| 428 | 1330 |
| 1331 ;;; Bind @code{my-command} to the middle mouse button. | |
| 1332 (global-set-key 'button2 'my-command) | |
| 1333 | |
| 1334 ;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}} | |
| 1335 ;;; in the keymap that is in force when you are running @code{dired}. | |
| 1336 (define-key dired-mode-map '(meta control button3) 'my-command) | |
| 1337 | |
| 1338 @end example | |
| 1339 | |
| 1340 @comment ;; note that these next four lines are not synonymous: | |
| 1341 @comment ;; | |
| 1342 @comment (global-set-key '(meta control delete) 'my-command) | |
| 1343 @comment (global-set-key '(meta control backspace) 'my-command) | |
| 1344 @comment (global-set-key '(meta control h) 'my-command) | |
| 1345 @comment (global-set-key '(meta control H) 'my-command) | |
| 1137 | 1346 @comment |
| 428 | 1347 @comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''. |
| 1348 @comment ;; | |
| 1349 @comment (global-set-key "\^J" 'my-command) | |
| 1350 | |
| 1351 @node Key Bindings Using Strings | |
| 1137 | 1352 @subsubsection Using Strings for Changing Key Bindings |
| 428 | 1353 |
| 1354 For backward compatibility, you can still use strings to represent | |
| 1355 key sequences. Thus you can use commands like the following: | |
| 1356 | |
| 1357 @example | |
| 1358 ;;; Bind @code{end-of-line} to @kbd{C-f} | |
| 1359 (global-set-key "\C-f" 'end-of-line) | |
| 1360 @end example | |
| 1361 | |
| 1362 Note, however, that in some cases you may be binding more than one | |
| 1137 | 1363 key sequence by using a single command. This situation can |
| 428 | 1364 arise because in ASCII, @kbd{C-i} and @key{TAB} have |
| 1365 the same representation. Therefore, when Emacs sees: | |
| 1366 | |
| 1367 @example | |
| 1368 (global-set-key "\C-i" 'end-of-line) | |
| 1369 @end example | |
| 1370 | |
| 1371 it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}. | |
| 1372 The solution XEmacs adopts is to bind both of these key | |
| 1373 sequences. | |
| 1374 | |
| 1375 @cindex redefining keys | |
| 1376 After binding a command to two key sequences with a form like: | |
| 1377 | |
| 1378 @example | |
| 440 | 1379 (define-key global-map "\^X\^I" 'command-1) |
| 428 | 1380 @end example |
| 1381 | |
| 1382 it is possible to redefine only one of those sequences like so: | |
| 1383 | |
| 1384 @example | |
| 440 | 1385 (define-key global-map [(control x) (control i)] 'command-2) |
| 1386 (define-key global-map [(control x) tab] 'command-3) | |
| 428 | 1387 @end example |
| 1388 | |
| 1389 This applies only when running under a window system. If you are | |
| 1390 talking to Emacs through an ASCII-only channel, you do not get any of | |
| 1391 these features. | |
| 1392 | |
| 1393 Here is a table of pairs of key sequences that behave in a | |
| 1394 similar fashion: | |
| 1395 | |
| 1396 @example | |
| 1137 | 1397 control h backspace |
| 428 | 1398 control l clear |
| 1137 | 1399 control i tab |
| 1400 control m return | |
| 1401 control j linefeed | |
| 428 | 1402 control [ escape |
| 1403 control @@ control space | |
| 1404 @end example | |
| 1405 | |
| 1406 @node Disabling | |
| 1407 @subsection Disabling Commands | |
| 1408 @cindex disabled command | |
| 1409 | |
| 1410 Disabling a command marks it as requiring confirmation before it | |
| 1411 can be executed. The purpose of disabling a command is to prevent | |
| 1412 beginning users from executing it by accident and being confused. | |
| 1413 | |
| 1414 The direct mechanism for disabling a command is to have a non-@code{nil} | |
| 1415 @code{disabled} property on the Lisp symbol for the command. These | |
| 442 | 1416 properties are normally set by the user's init file with |
| 428 | 1417 Lisp expressions such as: |
| 1418 | |
| 1419 @example | |
| 1420 (put 'delete-region 'disabled t) | |
| 1421 @end example | |
| 1422 | |
| 442 | 1423 @xref{Init File}. |
| 1424 | |
| 428 | 1425 If the value of the @code{disabled} property is a string, that string |
| 1426 is included in the message printed when the command is used: | |
| 1427 | |
| 1428 @example | |
| 1429 (put 'delete-region 'disabled | |
| 1430 "Text deleted this way cannot be yanked back!\n") | |
| 1431 @end example | |
| 1432 | |
| 1433 @findex disable-command | |
| 1434 @findex enable-command | |
| 442 | 1435 You can disable a command either by editing the init file |
| 428 | 1436 directly or with the command @kbd{M-x disable-command}, which edits the |
| 442 | 1437 init file for you. @xref{Init File}. |
| 428 | 1438 |
| 1439 When you attempt to invoke a disabled command interactively in Emacs, | |
| 1440 a window is displayed containing the command's name, its | |
| 1441 documentation, and some instructions on what to do next; then | |
| 1442 Emacs asks for input saying whether to execute the command as requested, | |
| 1443 enable it and execute, or cancel it. If you decide to enable the | |
| 1444 command, you are asked whether to do this permanently or just for the | |
| 1445 current session. Enabling permanently works by automatically editing | |
| 442 | 1446 your init file. You can use @kbd{M-x enable-command} at any |
| 428 | 1447 time to enable any command permanently. |
| 1448 | |
| 1449 Whether a command is disabled is independent of what key is used to | |
| 1450 invoke it; it also applies if the command is invoked using @kbd{M-x}. | |
| 1451 Disabling a command has no effect on calling it as a function from Lisp | |
| 1452 programs. | |
| 1453 | |
| 1454 @node Syntax | |
| 1455 @section The Syntax Table | |
| 1456 @cindex syntax table | |
| 1457 | |
| 1458 All the Emacs commands which parse words or balance parentheses are | |
| 1459 controlled by the @dfn{syntax table}. The syntax table specifies which | |
| 1460 characters are opening delimiters, which are parts of words, which are | |
| 1461 string quotes, and so on. Actually, each major mode has its own syntax | |
| 1462 table (though sometimes related major modes use the same one) which it | |
| 1463 installs in each buffer that uses that major mode. The syntax table | |
| 1464 installed in the current buffer is the one that all commands use, so we | |
| 1465 call it ``the'' syntax table. A syntax table is a Lisp object, a vector of | |
| 1466 length 256 whose elements are numbers. | |
| 1467 | |
| 1468 @menu | |
| 1469 * Entry: Syntax Entry. What the syntax table records for each character. | |
| 1470 * Change: Syntax Change. How to change the information. | |
| 1471 @end menu | |
| 1472 | |
| 1473 @node Syntax Entry | |
| 1474 @subsection Information About Each Character | |
| 1475 | |
| 1476 The syntax table entry for a character is a number that encodes six | |
| 1477 pieces of information: | |
| 1478 | |
| 1479 @itemize @bullet | |
| 1480 @item | |
| 1481 The syntactic class of the character, represented as a small integer | |
| 1482 @item | |
| 1483 The matching delimiter, for delimiter characters only | |
| 1484 (the matching delimiter of @samp{(} is @samp{)}, and vice versa) | |
| 1485 @item | |
| 1486 A flag saying whether the character is the first character of a | |
| 1487 two-character comment starting sequence | |
| 1488 @item | |
| 1489 A flag saying whether the character is the second character of a | |
| 1490 two-character comment starting sequence | |
| 1491 @item | |
| 1492 A flag saying whether the character is the first character of a | |
| 1493 two-character comment ending sequence | |
| 1494 @item | |
| 1495 A flag saying whether the character is the second character of a | |
| 1496 two-character comment ending sequence | |
| 1497 @end itemize | |
| 1498 | |
| 1499 The syntactic classes are stored internally as small integers, but are | |
| 1500 usually described to or by the user with characters. For example, @samp{(} | |
| 1501 is used to specify the syntactic class of opening delimiters. Here is a | |
| 1502 table of syntactic classes, with the characters that specify them. | |
| 1503 | |
| 1504 @table @samp | |
| 871 | 1505 @item @w{-} |
| 2736 | 1506 The class of whitespace characters. Avoid use of the formerly |
| 1507 advertised @w{ }, because it is not supported by GNU Emacs. | |
| 428 | 1508 @item w |
| 1509 The class of word-constituent characters. | |
| 1510 @item _ | |
| 1511 The class of characters that are part of symbol names but not words. | |
| 1512 This class is represented by @samp{_} because the character @samp{_} | |
| 1513 has this class in both C and Lisp. | |
| 1514 @item . | |
| 1515 The class of punctuation characters that do not fit into any other | |
| 1516 special class. | |
| 1517 @item ( | |
| 1518 The class of opening delimiters. | |
| 1519 @item ) | |
| 1520 The class of closing delimiters. | |
| 1521 @item ' | |
| 1522 The class of expression-adhering characters. These characters are | |
| 1523 part of a symbol if found within or adjacent to one, and are part | |
| 1524 of a following expression if immediately preceding one, but are like | |
| 1525 whitespace if surrounded by whitespace. | |
| 1526 @item " | |
| 1527 The class of string-quote characters. They match each other in pairs, | |
| 1528 and the characters within the pair all lose their syntactic | |
| 1529 significance except for the @samp{\} and @samp{/} classes of escape | |
| 1530 characters, which can be used to include a string-quote inside the | |
| 1531 string. | |
| 1532 @item $ | |
| 1533 The class of self-matching delimiters. This is intended for @TeX{}'s | |
| 1534 @samp{$}, which is used both to enter and leave math mode. Thus, | |
| 1535 a pair of matching @samp{$} characters surround each piece of math mode | |
| 1536 @TeX{} input. A pair of adjacent @samp{$} characters act like a single | |
| 1537 one for purposes of matching. | |
| 1538 | |
| 1539 @item / | |
| 1540 The class of escape characters that always just deny the following | |
| 1541 character its special syntactic significance. The character after one | |
| 1542 of these escapes is always treated as alphabetic. | |
| 1543 @item \ | |
| 1544 The class of C-style escape characters. In practice, these are | |
| 1545 treated just like @samp{/}-class characters, because the extra | |
| 1546 possibilities for C escapes (such as being followed by digits) have no | |
| 1547 effect on where the containing expression ends. | |
| 1548 @item < | |
| 1549 The class of comment-starting characters. Only single-character | |
| 1550 comment starters (such as @samp{;} in Lisp mode) are represented this | |
| 1551 way. | |
| 1552 @item > | |
| 1553 The class of comment-ending characters. Newline has this syntax in | |
| 1554 Lisp mode. | |
| 1555 @end table | |
| 1556 | |
| 1557 @vindex parse-sexp-ignore-comments | |
| 1558 The characters flagged as part of two-character comment delimiters can | |
| 1559 have other syntactic functions most of the time. For example, @samp{/} and | |
| 1560 @samp{*} in C code, when found separately, have nothing to do with | |
| 1561 comments. The comment-delimiter significance overrides when the pair of | |
| 1562 characters occur together in the proper order. Only the list and sexp | |
| 1563 commands use the syntax table to find comments; the commands specifically | |
| 1564 for comments have other variables that tell them where to find comments. | |
| 1565 Moreover, the list and sexp commands notice comments only if | |
| 1566 @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set | |
| 1567 to @code{nil} in modes where comment-terminator sequences are liable to | |
| 1568 appear where there is no comment, for example, in Lisp mode where the | |
| 1569 comment terminator is a newline but not every newline ends a comment. | |
| 1570 | |
| 1571 @node Syntax Change | |
| 1572 @subsection Altering Syntax Information | |
| 1573 | |
| 1574 It is possible to alter a character's syntax table entry by storing a new | |
| 1575 number in the appropriate element of the syntax table, but it would be hard | |
| 1576 to determine what number to use. Emacs therefore provides a command that | |
| 1577 allows you to specify the syntactic properties of a character in a | |
| 1578 convenient way. | |
| 1579 | |
| 1580 @findex modify-syntax-entry | |
| 1581 @kbd{M-x modify-syntax-entry} is the command to change a character's | |
| 1582 syntax. It can be used interactively and is also used by major | |
| 1583 modes to initialize their own syntax tables. Its first argument is the | |
| 1584 character to change. The second argument is a string that specifies the | |
| 1585 new syntax. When called from Lisp code, there is a third, optional | |
| 1586 argument, which specifies the syntax table in which to make the change. If | |
| 1587 not supplied, or if this command is called interactively, the third | |
| 1588 argument defaults to the current buffer's syntax table. | |
| 1589 | |
| 1590 @enumerate | |
| 1591 @item | |
| 1592 The first character in the string specifies the syntactic class. It | |
| 1593 is one of the characters in the previous table (@pxref{Syntax Entry}). | |
| 1594 | |
| 1595 @item | |
| 1596 The second character is the matching delimiter. For a character that | |
| 1597 is not an opening or closing delimiter, this should be a space, and may | |
| 1598 be omitted if no following characters are needed. | |
| 1599 | |
| 1600 @item | |
| 1601 The remaining characters are flags. The flag characters allowed are: | |
| 1602 | |
| 1603 @table @samp | |
| 1604 @item 1 | |
| 1605 Flag this character as the first of a two-character comment starting sequence. | |
| 1606 @item 2 | |
| 1607 Flag this character as the second of a two-character comment starting sequence. | |
| 1608 @item 3 | |
| 1609 Flag this character as the first of a two-character comment ending sequence. | |
| 1610 @item 4 | |
| 1611 Flag this character as the second of a two-character comment ending sequence. | |
| 1612 @end table | |
| 1613 @end enumerate | |
| 1614 | |
| 1615 @kindex C-h s | |
| 1616 @findex describe-syntax | |
| 1617 Use @kbd{C-h s} (@code{describe-syntax}) to display a description of | |
| 1618 the contents of the current syntax table. The description of each | |
| 1619 character includes both the string you have to pass to | |
| 1620 @code{modify-syntax-entry} to set up that character's current syntax, | |
| 1621 and some English to explain that string if necessary. | |
| 1622 | |
| 1623 @node Init File | |
| 442 | 1624 @section The Init File |
| 428 | 1625 @cindex init file |
| 1626 @cindex Emacs initialization file | |
| 1627 @cindex key rebinding, permanent | |
| 1628 @cindex rebinding keys, permanently | |
| 1629 | |
| 442 | 1630 When you start Emacs, it normally loads either @file{.xemacs/init.el} |
| 1631 or the file @file{.emacs} (whichever comes first) in your home directory. | |
| 1632 This file, if it exists, should contain Lisp code. It is called your | |
| 1633 initialization file or @dfn{init file}. Use the command line switch | |
| 1634 @samp{-q} to tell Emacs whether to load an init file (@pxref{Entering | |
| 1635 Emacs}). Use the command line switch @samp{-user-init-file} | |
| 1636 (@pxref{Command Switches}) to tell Emacs to load a different file | |
| 1637 instead of @file{~/.xemacs/init.el}/@file{~/.emacs}. | |
| 1638 | |
| 1639 When the init file is read, the variable @code{user-init-file} says | |
| 1640 which init file was loaded. | |
| 428 | 1641 |
| 1642 At some sites there is a @dfn{default init file}, which is the | |
| 1643 library named @file{default.el}, found via the standard search path for | |
| 1644 libraries. The Emacs distribution contains no such library; your site | |
| 1645 may create one for local customizations. If this library exists, it is | |
| 1646 loaded whenever you start Emacs. But your init file, if any, is loaded | |
| 1647 first; if it sets @code{inhibit-default-init} non-@code{nil}, then | |
| 1648 @file{default} is not loaded. | |
| 1649 | |
| 442 | 1650 If you have a large amount of code in your init file, you should |
| 1651 byte-compile it to @file{~/.xemacs/init.elc} or @file{~/.emacs.elc}. | |
| 428 | 1652 |
| 1653 @menu | |
| 1654 * Init Syntax:: Syntax of constants in Emacs Lisp. | |
| 1655 * Init Examples:: How to do some things with an init file. | |
| 1656 * Terminal Init:: Each terminal type can have an init file. | |
| 1657 @end menu | |
| 1658 | |
| 1659 @node Init Syntax | |
| 1660 @subsection Init File Syntax | |
| 1661 | |
| 442 | 1662 The init file contains one or more Lisp function call |
| 428 | 1663 expressions. Each consists of a function name followed by |
| 1664 arguments, all surrounded by parentheses. For example, @code{(setq | |
| 1665 fill-column 60)} represents a call to the function @code{setq} which is | |
| 1666 used to set the variable @code{fill-column} (@pxref{Filling}) to 60. | |
| 1667 | |
| 1668 The second argument to @code{setq} is an expression for the new value | |
| 1669 of the variable. This can be a constant, a variable, or a function call | |
| 442 | 1670 expression. In the init file, constants are used most of the time. |
| 428 | 1671 They can be: |
| 1672 | |
| 1673 @table @asis | |
| 1674 @item Numbers | |
| 1675 Integers are written in decimal, with an optional initial minus sign. | |
| 1676 | |
| 1677 If a sequence of digits is followed by a period and another sequence | |
| 1678 of digits, it is interpreted as a floating point number. | |
| 1679 | |
| 1680 The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to | |
| 1681 represent numbers in binary, octal, and hexadecimal notation (or radix). | |
| 1682 | |
| 1683 @item Strings | |
| 1684 Lisp string syntax is the same as C string syntax with a few extra | |
| 1685 features. Use a double-quote character to begin and end a string constant. | |
| 1686 | |
| 1687 Newlines and special characters may be present literally in strings. They | |
| 1688 can also be represented as backslash sequences: @samp{\n} for newline, | |
| 1689 @samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab, | |
| 1690 @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a | |
| 1691 backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the | |
| 1692 character whose octal code is @var{ooo}. Backslash and double-quote are | |
| 1693 the only characters for which backslash sequences are mandatory. | |
| 1694 | |
| 1695 You can use @samp{\C-} as a prefix for a control character, as in | |
| 1696 @samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for | |
| 1697 a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for | |
| 1698 Control-Meta-A.@refill | |
| 1699 | |
| 1700 @item Characters | |
| 1701 Lisp character constant syntax consists of a @samp{?} followed by | |
| 1702 either a character or an escape sequence starting with @samp{\}. | |
| 1703 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that | |
| 1704 strings and characters are not interchangeable in Lisp; some contexts | |
| 1705 require one and some contexts require the other. | |
| 1706 | |
| 1707 @item True | |
| 1708 @code{t} stands for `true'. | |
| 1709 | |
| 1710 @item False | |
| 1711 @code{nil} stands for `false'. | |
| 1712 | |
| 1713 @item Other Lisp objects | |
| 1714 Write a single-quote (') followed by the Lisp object you want. | |
| 1715 @end table | |
| 1716 | |
| 1717 @node Init Examples | |
| 1718 @subsection Init File Examples | |
| 1719 | |
| 1720 Here are some examples of doing certain commonly desired things with | |
| 1721 Lisp expressions: | |
| 1722 | |
| 1723 @itemize @bullet | |
| 1724 @item | |
| 1725 Make @key{TAB} in C mode just insert a tab if point is in the middle of a | |
| 1726 line. | |
| 1727 | |
| 1728 @example | |
| 1729 (setq c-tab-always-indent nil) | |
| 1730 @end example | |
| 1731 | |
| 1732 Here we have a variable whose value is normally @code{t} for `true' | |
| 1733 and the alternative is @code{nil} for `false'. | |
| 1734 | |
| 1735 @item | |
| 1736 Make searches case sensitive by default (in all buffers that do not | |
| 1737 override this). | |
| 1738 | |
| 1739 @example | |
| 1740 (setq-default case-fold-search nil) | |
| 1741 @end example | |
| 1742 | |
| 1743 This sets the default value, which is effective in all buffers that do | |
| 1744 not have local values for the variable. Setting @code{case-fold-search} | |
| 1745 with @code{setq} affects only the current buffer's local value, which | |
| 1746 is probably not what you want to do in an init file. | |
| 1747 | |
| 1748 @item | |
| 1749 Make Text mode the default mode for new buffers. | |
| 1750 | |
| 1751 @example | |
| 1752 (setq default-major-mode 'text-mode) | |
| 1753 @end example | |
| 1754 | |
| 1755 Note that @code{text-mode} is used because it is the command for entering | |
| 1756 the mode we want. A single-quote is written before it to make a symbol | |
| 1757 constant; otherwise, @code{text-mode} would be treated as a variable name. | |
| 1758 | |
| 1759 @item | |
| 1760 Turn on Auto Fill mode automatically in Text mode and related modes. | |
| 1761 | |
| 1762 @example | |
| 1763 (setq text-mode-hook | |
| 1764 '(lambda () (auto-fill-mode 1))) | |
| 1765 @end example | |
| 1766 | |
| 1767 Here we have a variable whose value should be a Lisp function. The | |
| 1768 function we supply is a list starting with @code{lambda}, and a single | |
| 1769 quote is written in front of it to make it (for the purpose of this | |
| 1770 @code{setq}) a list constant rather than an expression. Lisp functions | |
| 1771 are not explained here; for mode hooks it is enough to know that | |
| 1772 @code{(auto-fill-mode 1)} is an expression that will be executed when | |
| 1773 Text mode is entered. You could replace it with any other expression | |
| 1774 that you like, or with several expressions in a row. | |
| 1775 | |
| 1776 @example | |
| 1777 (setq text-mode-hook 'turn-on-auto-fill) | |
| 1778 @end example | |
| 1779 | |
| 1780 This is another way to accomplish the same result. | |
| 1781 @code{turn-on-auto-fill} is a symbol whose function definition is | |
| 1782 @code{(lambda () (auto-fill-mode 1))}. | |
| 1783 | |
| 1784 @item | |
| 1785 Load the installed Lisp library named @file{foo} (actually a file | |
| 1786 @file{foo.elc} or @file{foo.el} in a standard Emacs directory). | |
| 1787 | |
| 1788 @example | |
| 1789 (load "foo") | |
| 1790 @end example | |
| 1791 | |
| 1792 When the argument to @code{load} is a relative pathname, not starting | |
| 1793 with @samp{/} or @samp{~}, @code{load} searches the directories in | |
| 1794 @code{load-path} (@pxref{Loading}). | |
| 1795 | |
| 1796 @item | |
| 1797 Load the compiled Lisp file @file{foo.elc} from your home directory. | |
| 1798 | |
| 1799 @example | |
| 1800 (load "~/foo.elc") | |
| 1801 @end example | |
| 1802 | |
| 1803 Here an absolute file name is used, so no searching is done. | |
| 1804 | |
| 1805 @item | |
| 1806 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}. | |
| 1807 | |
| 1808 @example | |
| 1809 (global-set-key "\C-xl" 'make-symbolic-link) | |
| 1810 @end example | |
| 1811 | |
| 1812 or | |
| 1813 | |
| 1814 @example | |
| 1815 (define-key global-map "\C-xl" 'make-symbolic-link) | |
| 1816 @end example | |
| 1817 | |
| 1818 Note once again the single-quote used to refer to the symbol | |
| 1819 @code{make-symbolic-link} instead of its value as a variable. | |
| 1820 | |
| 1821 @item | |
| 1822 Do the same thing for C mode only. | |
| 1823 | |
| 1824 @example | |
| 1825 (define-key c-mode-map "\C-xl" 'make-symbolic-link) | |
| 1826 @end example | |
| 1827 | |
| 1828 @item | |
| 1829 Bind the function key @key{F1} to a command in C mode. | |
| 1830 Note that the names of function keys must be lower case. | |
| 1831 | |
| 1832 @example | |
| 1833 (define-key c-mode-map 'f1 'make-symbolic-link) | |
| 1834 @end example | |
| 1835 | |
| 1836 @item | |
| 1837 Bind the shifted version of @key{F1} to a command. | |
| 1838 | |
| 1839 @example | |
| 1840 (define-key c-mode-map '(shift f1) 'make-symbolic-link) | |
| 1841 @end example | |
| 1842 | |
| 1843 @item | |
| 1844 Redefine all keys which now run @code{next-line} in Fundamental mode | |
| 1845 to run @code{forward-line} instead. | |
| 1846 | |
| 1847 @example | |
| 1848 (substitute-key-definition 'next-line 'forward-line | |
| 1849 global-map) | |
| 1850 @end example | |
| 1851 | |
| 1852 @item | |
| 1853 Make @kbd{C-x C-v} undefined. | |
| 1854 | |
| 1855 @example | |
| 1856 (global-unset-key "\C-x\C-v") | |
| 1857 @end example | |
| 1858 | |
| 1859 One reason to undefine a key is so that you can make it a prefix. | |
| 1860 Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v} | |
| 1861 a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition | |
| 1862 first. | |
| 1863 | |
| 1864 @item | |
| 1865 Make @samp{$} have the syntax of punctuation in Text mode. | |
| 1866 Note the use of a character constant for @samp{$}. | |
| 1867 | |
| 1868 @example | |
| 1869 (modify-syntax-entry ?\$ "." text-mode-syntax-table) | |
| 1870 @end example | |
| 1871 | |
| 1872 @item | |
| 1873 Enable the use of the command @code{eval-expression} without confirmation. | |
| 1874 | |
| 1875 @example | |
| 1876 (put 'eval-expression 'disabled nil) | |
| 1877 @end example | |
| 1878 @end itemize | |
| 1879 | |
| 1880 @node Terminal Init | |
| 1881 @subsection Terminal-Specific Initialization | |
| 1882 | |
| 1883 Each terminal type can have a Lisp library to be loaded into Emacs when | |
| 1884 it is run on that type of terminal. For a terminal type named | |
| 1885 @var{termtype}, the library is called @file{term/@var{termtype}} and it is | |
| 1886 found by searching the directories @code{load-path} as usual and trying the | |
| 1887 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the | |
| 1888 subdirectory @file{term} of the directory where most Emacs libraries are | |
| 1889 kept.@refill | |
| 1890 | |
| 1891 The usual purpose of the terminal-specific library is to define the | |
| 1892 escape sequences used by the terminal's function keys using the library | |
| 1893 @file{keypad.el}. See the file | |
| 1894 @file{term/vt100.el} for an example of how this is done.@refill | |
| 1895 | |
| 1896 When the terminal type contains a hyphen, only the part of the name | |
| 1897 before the first hyphen is significant in choosing the library name. | |
| 1898 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use | |
| 1899 the library @file{term/aaa}. The code in the library can use | |
| 1900 @code{(getenv "TERM")} to find the full terminal type name.@refill | |
| 1901 | |
| 1902 @vindex term-file-prefix | |
| 1903 The library's name is constructed by concatenating the value of the | |
| 442 | 1904 variable @code{term-file-prefix} and the terminal type. Your init |
| 428 | 1905 file can prevent the loading of the terminal-specific library by setting |
| 442 | 1906 @code{term-file-prefix} to @code{nil}. @xref{Init File}. |
| 428 | 1907 |
| 1908 @vindex term-setup-hook | |
| 1909 The value of the variable @code{term-setup-hook}, if not @code{nil}, is | |
| 1910 called as a function of no arguments at the end of Emacs initialization, | |
| 442 | 1911 after both your init file and any terminal-specific library have been |
| 1912 read. @xref{Init File}. You can set the value in the init file to | |
| 1913 override part of any of the terminal-specific libraries and to define | |
| 428 | 1914 initializations for terminals that do not have a library.@refill |
| 1915 | |
| 1916 @node Audible Bell | |
| 1917 @section Changing the Bell Sound | |
| 1918 @cindex audible bell, changing | |
| 1919 @cindex bell, changing | |
| 1920 @vindex sound-alist | |
| 1921 @findex load-default-sounds | |
| 1922 @findex play-sound | |
| 1923 | |
| 1924 You can now change how the audible bell sounds using the variable | |
| 1925 @code{sound-alist}. | |
| 1926 | |
| 1927 @code{sound-alist}'s value is an list associating symbols with, among | |
| 1928 other things, strings of audio-data. When @code{ding} is called with | |
| 1929 one of the symbols, the associated sound data is played instead of the | |
| 1930 standard beep. This only works if you are logged in on the console of a | |
| 1931 machine with audio hardware. To listen to a sound of the provided type, | |
| 1932 call the function @code{play-sound} with the argument @var{sound}. You | |
| 1137 | 1933 can also set the volume of the sound with the optional argument |
| 428 | 1934 @var{volume}.@refill |
| 1935 @cindex ding | |
| 1936 | |
| 1937 Each element of @code{sound-alist} is a list describing a sound. | |
| 1938 The first element of the list is the name of the sound being defined. | |
| 1939 Subsequent elements of the list are alternating keyword/value pairs: | |
| 1940 | |
| 1941 @table @code | |
| 1942 @item sound | |
| 1137 | 1943 A string of raw sound data, or the name of another sound to play. |
| 428 | 1944 The symbol @code{t} here means use the default X beep. |
| 1945 | |
| 1946 @item volume | |
| 1947 An integer from 0-100, defaulting to @code{bell-volume}. | |
| 1948 | |
| 1949 @item pitch | |
| 1950 If using the default X beep, the pitch (Hz) to generate. | |
| 1951 | |
| 1952 @item duration | |
| 1953 If using the default X beep, the duration (milliseconds). | |
| 1954 @end table | |
| 1955 | |
| 1956 For compatibility, elements of `sound-alist' may also be of the form: | |
| 1957 | |
| 1958 @example | |
| 1959 ( @var{sound-name} . @var{<sound>} ) | |
| 1960 ( @var{sound-name} @var{<volume>} @var{<sound>} ) | |
| 1961 @end example | |
| 1962 | |
| 1963 You should probably add things to this list by calling the function | |
| 1964 @code{load-sound-file}. | |
| 1965 | |
| 1966 Note that you can only play audio data if running on the console screen | |
| 1967 of a machine with audio hardware which emacs understands, which at this | |
| 1968 time means a Sun SparcStation, SGI, or HP9000s700. | |
| 1969 | |
| 1970 Also note that the pitch, duration, and volume options are available | |
| 1971 everywhere, but most X servers ignore the `pitch' option. | |
| 1972 | |
| 1973 @vindex bell-volume | |
| 1974 The variable @code{bell-volume} should be an integer from 0 to 100, | |
| 1975 with 100 being loudest, which controls how loud the sounds emacs makes | |
| 1976 should be. Elements of the @code{sound-alist} may override this value. | |
| 1977 This variable applies to the standard X bell sound as well as sound files. | |
| 1978 | |
| 1979 If the symbol @code{t} is in place of a sound-string, Emacs uses the | |
| 1137 | 1980 default X beep. This allows you to define beep-types of |
| 428 | 1981 different volumes even when not running on the console. |
| 1982 | |
| 1983 @findex load-sound-file | |
| 1984 You can add things to this list by calling the function | |
| 1985 @code{load-sound-file}, which reads in an audio-file and adds its data to | |
| 1986 the sound-alist. You can specify the sound with the @var{sound-name} | |
| 1987 argument and the file into which the sounds are loaded with the | |
| 1988 @var{filename} argument. The optional @var{volume} argument sets the | |
| 1989 volume. | |
| 1990 | |
| 1991 @code{load-sound-file (@var{filename sound-name} &optional @var{volume})} | |
| 1992 | |
| 1993 To load and install some sound files as beep-types, use the function | |
| 1994 @code{load-default-sounds} (note that this only works if you are on | |
| 1995 display 0 of a machine with audio hardware). | |
| 1996 | |
| 1997 The following beep-types are used by Emacs itself. Other Lisp | |
| 1998 packages may use other beep types, but these are the ones that the C | |
| 1999 kernel of Emacs uses. | |
| 2000 | |
| 2001 @table @code | |
| 2002 @item auto-save-error | |
| 2003 An auto-save does not succeed | |
| 2004 | |
| 2005 @item command-error | |
| 2006 The Emacs command loop catches an error | |
| 2007 | |
| 2008 @item undefined-key | |
| 2009 You type a key that is undefined | |
| 2010 | |
| 440 | 2011 @item undefined-click |
| 428 | 2012 You use an undefined mouse-click combination |
| 2013 | |
| 440 | 2014 @item no-completion |
| 428 | 2015 Completion was not possible |
| 2016 | |
| 440 | 2017 @item y-or-n-p |
| 428 | 2018 You type something other than the required @code{y} or @code{n} |
| 2019 | |
| 1137 | 2020 @item yes-or-no-p |
| 428 | 2021 You type something other than @code{yes} or @code{no} |
| 2022 @end table | |
| 2023 | |
| 2024 @comment node-name, next, previous, up | |
| 2025 @node Faces | |
| 2026 @section Faces | |
| 2027 | |
| 2028 XEmacs has objects called extents and faces. An @dfn{extent} | |
| 2029 is a region of text and a @dfn{face} is a collection of textual | |
| 2030 attributes, such as fonts and colors. Every extent is displayed in some | |
| 2031 face; therefore, changing the properties of a face immediately updates the | |
| 2032 display of all associated extents. Faces can be frame-local: you can | |
| 2033 have a region of text that displays with completely different | |
| 2034 attributes when its buffer is viewed from a different X window. | |
| 2035 | |
| 2036 The display attributes of faces may be specified either in Lisp or through | |
| 2037 the X resource manager. | |
| 2038 | |
| 3387 | 2039 Basic Xft support has been merged into the mainline, and it looks pretty |
| 2040 good. However, customization UI and documentation still leaves a lot to | |
| 2041 be desired. Here's a first cut, as a separate node. | |
| 2042 | |
| 2043 @menu | |
| 2044 * Xft Font Customization:: | |
| 2045 @end menu | |
| 2046 | |
| 428 | 2047 @subsection Customizing Faces |
| 2048 | |
| 2049 You can change the face of an extent with the functions in | |
| 2050 this section. All the functions prompt for a @var{face} as an | |
| 2051 argument; use completion for a list of possible values. | |
| 2052 | |
| 2053 @table @kbd | |
| 2054 @item M-x invert-face | |
| 2055 Swap the foreground and background colors of the given @var{face}. | |
| 2056 @item M-x make-face-bold | |
| 2057 Make the font of the given @var{face} bold. When called from a | |
| 2058 program, returns @code{nil} if this is not possible. | |
| 2059 @item M-x make-face-bold-italic | |
| 1137 | 2060 Make the font of the given @var{face} bold italic. |
| 428 | 2061 When called from a program, returns @code{nil} if not possible. |
| 2062 @item M-x make-face-italic | |
| 1137 | 2063 Make the font of the given @var{face} italic. |
| 428 | 2064 When called from a program, returns @code{nil} if not possible. |
| 2065 @item M-x make-face-unbold | |
| 1137 | 2066 Make the font of the given @var{face} non-bold. |
| 428 | 2067 When called from a program, returns @code{nil} if not possible. |
| 2068 @item M-x make-face-unitalic | |
| 2069 Make the font of the given @var{face} non-italic. | |
| 2070 When called from a program, returns @code{nil} if not possible. | |
| 2071 @item M-x make-face-larger | |
| 2072 Make the font of the given @var{face} a little larger. | |
| 2073 When called from a program, returns @code{nil} if not possible. | |
| 2074 @item M-x make-face-smaller | |
| 2075 Make the font of the given @var{face} a little smaller. | |
| 2076 When called from a program, returns @code{nil} if not possible. | |
| 1137 | 2077 @item M-x set-face-background |
| 428 | 2078 Change the background color of the given @var{face}. |
| 2079 @item M-x set-face-background-pixmap | |
| 2080 Change the background pixmap of the given @var{face}. | |
| 1137 | 2081 @item M-x set-face-background-pixmap-file |
| 2082 A simpler version but with filename completion. | |
|
5080
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2083 @item M-x set-face-background-placement |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2084 Change the placement of the background pixmap of the given @var{face}. |
| 1137 | 2085 @item M-x set-face-font |
| 428 | 2086 Change the font of the given @var{face}. |
| 2087 @item M-x set-face-foreground | |
| 2088 Change the foreground color of the given @var{face}. | |
| 2089 @item M-x set-face-underline-p | |
| 2090 Change whether the given @var{face} is underlined. | |
| 2091 @end table | |
| 2092 | |
| 2093 @findex make-face-larger | |
| 2094 @findex make-face-smaller | |
| 2095 | |
| 2096 @findex invert-face | |
| 2097 You can exchange the foreground and background color of the selected | |
| 2098 @var{face} with the function @code{invert-face}. If the face does not | |
| 2099 specify both foreground and background, then its foreground and | |
| 2100 background are set to the background and foreground of the default face. | |
| 1137 | 2101 When calling this from a program, you can supply the optional argument |
| 428 | 2102 @var{frame} to specify which frame is affected; otherwise, all frames |
| 2103 are affected. | |
| 2104 | |
| 1142 | 2105 @findex make-face-bold |
| 2106 @findex make-face-bold-italic | |
| 2107 @findex make-face-italic | |
| 2108 @findex make-face-unbold | |
| 2109 @findex make-face-unitalic | |
| 2110 @vindex face-frob-from-locale-first | |
| 2111 The work of @code{make-face-bold}, @code{make-face-bold-italic}, | |
| 2112 @code{make-face-italic}, @code{make-face-unbold}, | |
| 2113 @code{make-face-unitalic} functions is affected by | |
| 2114 @code{face-frob-from-locale-first} variable. If it is @code{nil}, those | |
| 2115 functions first try to manipulate device specific data like X font names | |
| 2116 to obtain the desired font face specification. This may be unsuitable | |
| 2117 in environments using different font face specifications for different | |
| 2118 frames, non-Mule environments in particular. | |
| 2119 | |
| 2120 If the variable is non-@code{nil}, those functions first try to figure | |
| 2121 out whether the face font is the same as one of predefined faces: | |
| 2122 @code{default}, @code{bold}, @code{italic}, @code{bold-italic}. If it | |
| 2123 is the same, then the new face font specification is set to be the same | |
| 2124 as that of a corresponding predefined face. Thus if the predefined face | |
| 2125 is set up properly for different frames, the same will hold for the face | |
| 2126 being changed by the functions. This is the behavior one might desire | |
| 2127 in non-Mule environments mentioned above: face being changed still looks | |
| 2128 right in all frames. | |
| 2129 | |
| 2130 How predefined faces might be set up for different frames in such an | |
| 2131 environments is described in @ref{Face Resources}. | |
| 2132 | |
| 428 | 2133 @findex set-face-background |
| 2134 You can set the background color of the specified @var{face} with the | |
| 2135 function @code{set-face-background}. The argument @code{color} should | |
| 2136 be a string, the name of a color. When called from a program, if the | |
| 1137 | 2137 optional @var{frame} argument is provided, the face is changed only |
| 428 | 2138 in that frame; otherwise, it is changed in all frames. |
| 2139 | |
| 2140 @findex set-face-background-pixmap | |
| 2141 You can set the background pixmap of the specified @var{face} with the | |
| 2142 function @code{set-face-background-pixmap}. The pixmap argument | |
| 2143 @var{name} should be a string, the name of a file of pixmap data. The | |
| 2144 directories listed in the @code{x-bitmap-file-path} variable are | |
| 2145 searched. The bitmap may also be a list of the form @code{(@var{width | |
| 2146 height data})}, where @var{width} and @var{height} are the size in | |
| 2147 pixels, and @var{data} is a string containing the raw bits of the | |
| 2148 bitmap. If the optional @var{frame} argument is provided, the face is | |
| 2149 changed only in that frame; otherwise, it is changed in all frames. | |
| 2150 | |
| 2151 The variable @code{x-bitmap-file-path} takes as a value a list of the | |
| 2152 directories in which X bitmap files may be found. If the value is | |
| 2153 @code{nil}, the list is initialized from the @code{*bitmapFilePath} | |
| 2154 resource. | |
| 2155 | |
| 2156 If the environment variable @b{XBMLANGPATH} is set, then it is consulted | |
| 2157 before the @code{x-bitmap-file-path} variable. | |
| 2158 | |
| 1137 | 2159 @findex set-face-background-pixmap |
| 2160 Alternately, you can use a simpler version of | |
| 2161 @code{set-face-background-pixmap} called | |
| 2162 @code{set-face-background-pixmap-file}. This function does not give you | |
| 3111 | 2163 as much control on the pixmap instantiator, but provides filename |
| 1137 | 2164 completion. |
| 2165 | |
|
5080
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2166 @findex set-face-background-placement |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2167 You can set the placement of the background pixmap of the specified |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2168 @var{face} with the function @code{set-face-background-placement}. The |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2169 placement argument can be either @code{absolute} or @code{relative} (the |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2170 default). A @code{relative} placement means that the pixmap is attached |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2171 to the frame and moves with it. An @code{absolute} placement means that |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2172 the pixmap is rather attached to the frame's root window, so that when |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2173 you move the frame on the screen, it will appear to ``slide'' on the |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2174 pixmap. This placement mode can be used to achieve pseudo-translucency |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2175 for a frame, for example by setting the default face's background pixmap |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2176 to the root window's one. |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2177 |
| 428 | 2178 @findex set-face-font |
| 2179 You can set the font of the specified @var{face} with the function | |
| 2180 @code{set-face-font}. The @var{font} argument should be a string, the | |
| 2181 name of a font. When called from a program, if the | |
| 1137 | 2182 optional @var{frame} argument is provided, the face is changed only |
| 428 | 2183 in that frame; otherwise, it is changed in all frames. |
| 2184 | |
| 3111 | 2185 The syntax of the @var{font} argument varies according to platform. In |
| 2186 each of the following syntaxes, the example shows how to specify a | |
| 2187 14-point upright bold Courier font. | |
| 2188 | |
| 2189 @table @strong | |
| 2190 @item X11 | |
| 2191 The X11 syntax is defined by the @dfn{X Logical Font Descriptor} (XLFD) | |
| 2192 standard. An XLFD contains 14 fields each preceded by a hyphen: | |
| 2193 foundry, family, weight, slant, swidth, adstyle, pixelsize, pointsize, | |
| 2194 xresolution, yresolution, spacing, averagewidth, registry, and encoding. | |
| 2195 It is usually sufficient to specify family, weight, slant, pointsize, | |
| 2196 registry, and encoding, wildcarding the rest with @samp{*}. If you're | |
| 2197 not sure what's available, you can wildcard some of the fields usually | |
| 2198 specified, too. Here's our example font in XLFD syntax: | |
| 2199 @code{"-*-courier-bold-r-*-*-*-140-*-*-*-*-iso8859-*"}. | |
| 2200 The XLFD syntax is also used for GTK+ version 1. XLFD names must be | |
| 3510 | 2201 encoded in ISO-8859-1. |
| 3111 | 2202 |
| 2203 @item Xft | |
| 2204 The Xft syntax is defined by the @file{fontconfig} library | |
| 2205 @ref{Font Names,,,fontconfig}. It is less a font naming convention than | |
| 2206 a way to express any arbitrary subset of the font's properties in a | |
| 2207 syntax that is both human- and machine-readable. A @file{fontconfig} | |
| 2208 font name contains the family, a hyphen, and the pointsize, followed by | |
| 2209 an arbitrary sequence of properties. Each property consists of a colon, | |
| 2210 a keyword, an equals sign, and the property value. Here's our example | |
| 2211 font in @file{fontconfig} syntax: @code{"Courier-14:weight=bold"}. This | |
| 2212 syntax admits ``style abbreviations'' which can be user-defined. A | |
| 2213 style is a single keyword denoting a sequence of properties. So the | |
| 2214 example font may be abbreviated to @code{"Courier-14:bold"} ("bold" is a | |
| 2215 standard abbreviation for "weight=bold"). The @file{fontconfig} syntax | |
| 2216 is also used for GTK+ version 2. @file{fontconfig} names must be | |
| 2217 encoded in UTF-8. | |
| 2218 | |
| 2219 @item MS-Windows | |
| 2220 The MS Windows syntax is superficially similar to that of Xft but | |
| 2221 actually is more like XLFD. A font name consists of five fields, | |
| 2222 family, size, slant, weight, and encoding, each expressed as a keyword | |
| 2223 taking on standardized values (except family, which is just a name). | |
| 2224 Here's our example font in MS Windows syntax: | |
| 2225 @code{"Courier:14:Bold:Western"}. | |
| 2226 @end table | |
| 2227 | |
| 1137 | 2228 @findex set-face-foreground |
| 428 | 2229 You can set the foreground color of the specified @var{face} with the |
| 2230 function @code{set-face-foreground}. The argument @var{color} should be | |
| 2231 a string, the name of a color. If the optional @var{frame} argument is | |
| 2232 provided, the face is changed only in that frame; otherwise, it is | |
| 2233 changed in all frames. | |
| 2234 | |
| 2235 @findex set-face-underline-p | |
| 2236 You can set underline the specified @var{face} with the function | |
| 2237 @code{set-face-underline-p}. The argument @var{underline-p} can be used | |
| 2238 to make underlining an attribute of the face or not. If the optional | |
| 2239 @var{frame} argument is provided, the face is changed only in that | |
| 2240 frame; otherwise, it is changed in all frames. | |
| 2241 | |
| 3387 | 2242 |
| 2243 @node Xft Font Customization, , , Faces | |
| 2244 @section Xft Font Customization | |
| 2245 | |
| 2246 This section was written by @email{stephen@@xemacs.org,Stephen Turnbull}, | |
| 2247 and is very much a work in progress. I've tried to provide pointers to | |
| 2248 as much of the relevant information as possible, but many of the APIs | |
| 2249 and UIs are in flux, so it seemed more work than it was worth to | |
| 2250 completely translate the tables of constants, and so on. Feel free to | |
| 2251 ask for clarifications, @emph{etc.} Please Cc | |
| 2252 @email{xemacs-beta@@xemacs.org,the XEmacs Beta Testers' mailing list}, | |
| 2253 as that is the issue tracking channel of record, and there are a few | |
| 2254 others who can answer the questions or improve documentation when I'm | |
| 2255 not able to respond quickly. | |
| 2256 | |
| 2257 @c Don't blame Ben (or Eric and Matthias, for that matter). Feel free to | |
| 2258 @c add, edit, and share the blame, everybody! | |
| 2259 | |
| 2260 @c #### Make these @urlref's!! | |
| 2261 As of mid-2005, we have added support for the | |
| 2262 @file{Xft} library, which provides a more robust @emph{font | |
| 2263 configuration} mechanism via Keith Packard's @file{fontconfig} library; | |
| 2264 improved glyph rendering, including antialiasing, via the | |
| 2265 @file{freetype} library; and client-side rendering (saving bandwidth and | |
| 2266 server memory) via the @file{XRender extension}. | |
| 2267 | |
| 2268 @c #### Describe Alexey Gladkov and Yury Konovalov's work. | |
| 2269 | |
| 2270 @subheading Font configuration | |
| 2271 | |
| 2272 In XEmacs, font configuration is handled via @emph{faces}. Currently | |
| 2273 XEmacs uses a special type of @emph{font specifier} to map XEmacs | |
| 2274 locales to font names. Especially under X11, this can cause annoying | |
| 2275 problems because of the unreliability of X servers' mappings from | |
| 2276 @samp{XLFD} names to X11 fonts, over which XEmacs has no influence | |
| 2277 whatsoever. However, the @file{fontconfig} library which is used with | |
| 2278 @file{Xft} provides much more reliable mapping, along with a more | |
| 2279 reliably parsable naming scheme similar to that used by TrueType fonts | |
| 2280 on MS Windows and the Macintosh. | |
| 2281 | |
| 2282 @subheading fontconfig | |
| 2283 | |
| 2284 Fontconfig is dramatically different from the X model in several ways. | |
| 2285 In particular, when queried for a font @emph{fontconfig always returns a | |
| 2286 font}, whereas X queries may return ``not found.'' However, the font | |
| 2287 returned need not be anything like the desired font. This is not really | |
| 2288 a problem in practice, because users generally have a pretty good idea | |
| 2289 of what fonts are available on their display. However, users should be | |
| 2290 aware that as of XEmacs 21.5.26 the font selection internals have not | |
| 2291 been revised to account for this radically different model, so some | |
| 2292 surprising results are possible. | |
| 2293 | |
| 2294 From the user's point of view, @file{fontconfig} provides a naming | |
| 2295 convention which is @emph{precise}, @emph{accurate}, and | |
| 2296 @emph{convenient}. Precision means that all properties available in the | |
| 2297 programming API can be individually specified. Accuracy means that the | |
| 2298 truename of the font is exactly the list of all properties specified by | |
| 4488 | 2299 the font. Thus, the anomalies that occur with XLFDs on many servers |
| 3387 | 2300 (including modern Linux distributions with XFree86 or X.org servers) |
| 2301 cannot occur. Convenience is subjective, of course. However, | |
| 2302 @file{fontconfig} provides a configuration system which (1) explicitly | |
| 2303 specifies the defaults and substitutions that will be made in processing | |
| 2304 user queries, (2) allows the user to specify search configuration, | |
| 2305 abbreviations, substitutions, and defaults that override the system's, | |
| 2306 in the same format as used by system files, and (3) allows flexible | |
| 2307 aliases that can resolve to any of several actual fonts depending on | |
| 2308 which fonts are installed. | |
| 2309 | |
| 2310 Further, a @dfn{standard minimal configuration} is defined that ensures | |
| 2311 that at least the @emph{serif}, @emph{sans-serif}, and @emph{monospace} | |
| 2312 font aliases are available on all @file{fontconfig} systems. | |
| 2313 | |
| 2314 @subheading fontconfig font names | |
| 2315 | |
| 2316 @file{fontconfig} font names are very regular, and constitute a precise | |
| 2317 and extensible specification of a font's properties. | |
| 2318 | |
| 2319 The basic @file{fontconfig} font name has three components: the font | |
| 2320 family name, the size, and a list of named attribute fields. All | |
| 2321 attribute names and values are strings encoded in Unicode UTF-8, or | |
| 2322 decimal numbers with optional decimal point and fraction. The | |
| 2323 characters @samp{-}, @samp{:}, @samp{,}, @samp{=}, and @samp{\} are | |
| 2324 syntactically significant to @file{fontconfig}. They may be used in | |
| 2325 font name components by the familiar mechanism of backslash escaping. | |
| 2326 This simply removes any special meaning from the following character. | |
| 2327 It is always safe to use an escape even if it is not needed. | |
| 2328 | |
| 2329 Most string values are case-insensitive, but this is attribute-specific. | |
| 2330 | |
| 2331 The @dfn{font family name} is an arbitrary string, which may contain any | |
| 2332 character, including spaces, hyphens, and commas. Don't forget to | |
| 2333 escape hyphens, colons, commas, and backslashes! | |
| 2334 | |
| 2335 The @dfn{size} is a decimal number with optional decimal point and | |
| 2336 fractional part. It is interpreted as point size. | |
| 2337 | |
| 2338 A @dfn{named attribute field} is a key-value pair separated by an equal | |
| 2339 sign. Some attributes have predefined semantics. (These include such | |
| 2340 familiar attributes as @samp{slant} and @samp{dpi} -- note that | |
| 2341 @file{fontconfig} does not distinguish between vertical and horizontal | |
| 2342 resolution! | |
| 2343 | |
| 2344 The basic syntax of a font name is simple and regular. The @emph{font | |
| 2345 family name} comes first, followed by a hyphen and the @emph{size}, | |
| 2346 followed by a list of @emph{named attribute fields}, each introduced by | |
| 2347 a colon: | |
| 2348 | |
| 2349 @example | |
| 2350 @var{font family name}-@var{size}:@var{key1}=@var{value1}:@var{key2}=@var{value2}... | |
| 2351 @end example | |
| 2352 | |
| 2353 There are four extensions to the basic syntax. First, all of the | |
| 2354 fields are optional. If size is omitted, the hyphen should be omitted | |
| 2355 as well. There should never be a trailing colon. Note that | |
| 2356 @file{fontconfig} does @emph{not} interpret an omitted field as | |
| 2357 ``default to current.'' @file{fontconfig} does not have access to that | |
| 2358 context. Instead, omitted fields are filled in according to a set of | |
| 2359 defaults specified in the system @file{fonts.conf} file and in the | |
| 2360 user's @file{.fonts.cont} file. The user's configuration gets | |
| 2361 precedence, of course. | |
| 2362 | |
| 2363 The second is that the @emph{font family name}, the @emph{size}, and the | |
| 2364 @emph{value} component of a @emph{named attribute field} may be a | |
| 2365 comma-separated list of values. This is called a @dfn{pattern}. In | |
| 2366 queries, @file{fontconfig} tries to match each entry in the list in | |
| 2367 order. (I suspect that order of attributes is also significant. | |
| 2368 @emph{I.e.}, font family always gets highest precedence, followed by | |
| 2369 size, followed by the remaining named attributes. Testing and reports | |
| 2370 to the @email{xemacs-beta@@xemacs.org,XEmacs Beta Testers mailing list} | |
| 2371 are very welcome!) | |
| 2372 | |
| 2373 The third is the definition of @dfn{constants} to represent numerical | |
| 2374 values. For example, both @samp{slant} and @samp{weight} are defined as | |
| 2375 integer attributes, but the magnitudes are arbitrary; only the ordering | |
| 2376 and relative distances are useful. (``Relative distance'' is used to | |
| 2377 implement the concept that although strictly speaking @emph{italic} and | |
| 2378 @emph{oblique} are different faces, most users don't know the | |
| 2379 difference, and even professional typographers would agree that they are | |
| 2380 much closer to each other than either is to @emph{roman}.) So | |
| 2381 @emph{constants} like @samp{roman} (0) and @samp{italic} (100) are | |
| 2382 defined for @samp{slant}, and @samp{medium} (100) and @samp{bold} (200) | |
| 2383 are defined for @samp{weight}. | |
| 2384 | |
| 2385 The fourth is that a @dfn{style} may be defined as an alias for an | |
| 2386 instance of a @emph{named attribute field}, that is, specifying both key | |
| 2387 and value. The @emph{styles} @samp{bold}, an alias for | |
| 2388 @samp{weight=200}, and @samp{italic}, an alias for @samp{slant=100}, are | |
| 2389 commonly used. | |
| 2390 | |
| 2391 Styles and constants can be defined by the application. XEmacs | |
| 2392 currently defines none, but suggestions are welcome if some convenient | |
| 2393 alias is lacking from @file{fontconfig}. Note that we will not provide | |
| 2394 additional aliases where standard ones exist, @emph{e.g.}, @samp{heavy} | |
| 2395 as an additional alias for @samp{bold} would almost certainly be | |
| 2396 rejected. These cause more confusion than they are worth, and would | |
| 2397 decrease portability of user specifications to other applications. | |
| 2398 | |
| 2399 (Attributes can also be defined, but they must be implemented by the | |
| 2400 fonts to be useful. Until XEmacs provides its own fonts with | |
| 2401 non-standardized attributes, this is not useful.) | |
| 2402 | |
| 2403 Here are some examples of font names and query patterns: | |
| 2404 | |
| 2405 @example | |
| 2406 Times-12 12-point Times Roman | |
| 2407 Times-12:bold 12-point Times Bold | |
| 2408 Courier:italic Courier Italic in the default size | |
| 2409 Monospace:matrix=1 .1 0 1 The user's preferred monospace font | |
| 2410 with artificial obliquing | |
| 2411 Mikachan\-PB-16 16-point Mikachan-PB | |
| 2412 LucidaTypewriter,Courier-9 9-point LucidaTypewriter if available, | |
| 2413 otherwise 9-point Courier | |
| 2414 @end example | |
| 2415 | |
| 2416 Note how @emph{styles} are used in the second and third examples, how | |
| 2417 @samp{matrix} has a complex value containing spaces, and the | |
| 2418 escaped hyphen in the font family name @samp{Mikachan\-PB}. | |
| 2419 | |
| 2420 @c #### FIXME here and also in fontconfig.texi (in general-docs package). | |
| 2421 Here is a (somewhat outdated) list of current standard named attributes: | |
| 2422 | |
| 2423 @example | |
| 2424 Property CPP symbol Type Description | |
| 2425 | |
| 2426 family FC_FAMILY String Font family name | |
| 2427 style FC_STYLE String Font style. Overrides weight and slant | |
| 2428 slant FC_SLANT Int Italic, oblique or roman | |
| 2429 weight FC_WEIGHT Int Light, medium, demibold, bold or black | |
| 2430 size FC_SIZE Double Point size | |
| 2431 aspect FC_ASPECT Double Stretch glyphs horizontally, then hint | |
| 2432 pixelsize FC_PIXEL_SIZE Double Pixel size | |
| 2433 spacing FC_SPACING Int Proportional, monospace or charcell | |
| 2434 foundry FC_FOUNDRY String Font foundry name | |
| 2435 antialias FC_ANTIALIAS Bool Should glyphs be antialiased? | |
| 2436 hinting FC_HINTING Bool Should the rasterizer use hinting? | |
| 2437 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout | |
| 2438 autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter | |
| 2439 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data | |
| 2440 file FC_FILE String The filename holding the font | |
| 2441 index FC_INDEX Int The index of the font within the file | |
| 2442 ftface FC_FT_FACE FT_Face Use the specified FreeType face object | |
| 2443 rasterizer FC_RASTERIZER String Which rasterizer is in use | |
| 2444 outline FC_OUTLINE Bool Whether the glyphs are outlines | |
| 2445 scalable FC_SCALABLE Bool Whether glyphs can be scaled | |
| 2446 scale FC_SCALE Double Point->pixel conversion scale factor | |
| 2447 dpi FC_DPI Double Target dots per inch | |
| 2448 rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none | |
| 2449 - subpixel geometry | |
| 2450 source FC_SOURCE String X11, freetype | |
| 2451 minspace FC_MINSPACE Bool Eliminate leading from line spacing | |
| 2452 charset FC_CHARSET CharSet Unicode chars encoded by the font | |
| 2453 lang FC_LANG String List of RFC-3066-style languages | |
| 2454 this font supports | |
| 2455 fontversion FC_FONTVERSION Int From 'head' table | |
| 2456 @end example | |
| 2457 | |
| 2458 Here is a list of current standard constants: | |
| 2459 | |
| 2460 @example | |
| 2461 Constant Property CPP symbol | |
| 2462 | |
| 2463 light weight FC_WEIGHT_LIGHT | |
| 2464 medium weight FC_WEIGHT_MEDIUM | |
| 2465 demibold weight FC_WEIGHT_DEMIBOLD | |
| 2466 bold weight FC_WEIGHT_BOLD | |
| 2467 black weight FC_WEIGHT_BLACK | |
| 2468 roman slant FC_SLANT_ROMAN | |
| 2469 italic slant FC_SLANT_ITALIC | |
| 2470 oblique slant FC_SLANT_OBLIQUE | |
| 2471 proportional spacing FC_PROPORTIONAL | |
| 2472 mono spacing FC_MONO | |
| 2473 charcell spacing FC_CHARCELL | |
| 2474 unknown rgba FC_RGBA_UNKNOWN | |
| 2475 rgb rgba FC_RGBA_RGB | |
| 2476 bgr rgba FC_RGBA_BGR | |
| 2477 vrgb rgba FC_RGBA_VRGB | |
| 2478 vbgr rgba FC_RGBA_VBGR | |
| 2479 none rgba FC_RGBA_NONE | |
| 2480 @end example | |
| 2481 | |
| 2482 Note that this is the @file{fontconfig} API list; you can expect that | |
| 2483 XEmacs will define corresponding keywords by substituting @samp{:} for | |
| 2484 the leading @samp{FC_}, @samp{-} for @samp{_}, removing the key of the | |
| 2485 attribute if present, and lowercasing the name. Thus | |
| 2486 @samp{FC_WEIGHT_BOLD} becomes @samp{:bold}. | |
| 2487 @kbd{M-x apropos RET fc-.*-mapping} will give a list of variables each | |
| 2488 of which lists such keywords and their meanings. | |
| 2489 | |
| 2490 @subheading Font menus | |
| 2491 | |
| 2492 The @samp{Options->Font} and @samp{Options->Font Sizes} menus are | |
| 2493 broken, by design, not just by @file{Xft}. The problem is that many | |
| 2494 fonts are unavailable because they don't match the current size---which | |
| 2495 is very strange, since @file{Xft} fonts are of course scalable. But the | |
| 2496 whole idea of requiring that the font match the size is strange. And | |
| 2497 the @samp{Options->Font Weights} menu is just disabled, and has been for | |
| 2498 eons. | |
| 2499 | |
| 2500 @subheading X resources | |
| 2501 | |
| 2502 Currently there are @emph{four} treatments of font resources. There are | |
| 2503 the @samp{XEmacs.@var{face}.attributeFont} resources used to set a | |
| 2504 single global font specification. In the widgets, some (still) have a | |
| 2505 @samp{font} resource using the automatic @file{Xt} resource conversion | |
| 2506 to X's @samp{FontStruct}, some have separate @samp{font} and @samp{xftFont} | |
| 2507 resources with the former automatically converted to @samp{FontStruct} | |
| 2508 by @file{Xt} and the latter left as a string, to be converted to a | |
| 2509 fontconfig @samp{FcPattern} by | |
| 2510 @samp{FcParseName} later, and some have a single @samp{font} resource | |
| 2511 which is converted to @samp{FontStruct} by @file{Xt} or the latter left | |
| 2512 as a string, depending on whether @file{Xft} was enabled by | |
| 2513 @samp{configure} or not. | |
| 2514 | |
| 2515 Eventually these should be converted to use the face | |
| 2516 approach, perhaps with some way to set specifications for individual | |
| 2517 widgets, frames, or buffers. This will require some careful design work | |
| 2518 to incorporate face support in the widgets. Stephen's current thinking | |
| 2519 is that XEmacs should just accept any | |
| 2520 or all of @samp{font}, @samp{fontSet}, and @samp{fontList} resources, | |
| 2521 treat them all as lists of font names, either @samp{XLFD}- or | |
| 2522 @file{fontconfig}-style, parse them ourselves (ie, not use the @file{Xt} | |
| 2523 resource manager), and add them to font specifiers as appropriate. But | |
| 2524 this will require a bit of thought to obey POLA vis-a-vis usual @file{Xt} | |
| 2525 conventions. | |
| 2526 | |
| 2527 @subheading Specifiers, charsets, and languages | |
| 2528 | |
| 2529 Traditionally Mule uses a rather rigid and low-level abstraction, the | |
| 2530 @emph{charset}, to characterize font repertoires. Unfortunately, | |
| 2531 support for a given charset is generally neither necessary nor | |
| 2532 sufficient to support a language. Worse, in XEmacs's current | |
| 2533 implementation Xft doesn't help much. Instead you need to add the fonts | |
| 2534 for different charsets to the font specifier in the right order. | |
| 2535 | |
| 2536 There currently is no explicit way to specify that a particular font be | |
| 2537 used only for a given language. However, since many fonts support only | |
| 2538 a limited repertoire such as ISO 8859/1, you can use the precedence of | |
| 2539 specifications for a given specifier locale to get something of this | |
| 2540 effect for non-Latin character sets. This will normally work rather | |
| 2541 poorly for multiple Latin character sets, however, because the | |
| 2542 repertoires tend to have large amounts of overlap. Support for | |
| 2543 specifying font by @emph{language} as well as by character set is | |
| 2544 planned. | |
| 2545 | |
| 2546 Because fonts supporting other languages tend to support English as | |
| 2547 well, if you want to use one font for English and another for the other | |
| 2548 language, you must use the @code{append} method when adding font | |
| 2549 specifications for the @emph{other} language. | |
| 2550 | |
| 2551 However, this simple method leaves you with a problem if you want to | |
| 2552 change the other language's font: you have to remove the existing | |
| 2553 specification so it won't shadow the new one when you append. | |
| 2554 | |
| 2555 In order to provide a convenient way to change ``other-language fonts'', | |
| 2556 I use @code{remove-tag-set-append} and @code{define-specifier-tag} like | |
| 2557 this: | |
| 2558 | |
| 2559 @example | |
| 2560 (define-specifier-tag 'lang-ja) | |
| 2561 ;; No, I don't try to do real work with this font! But it makes it | |
| 2562 ;; obvious that I got the requested font. :-) | |
| 2563 (set-face-font 'default "AirCut-14") | |
| 2564 (set-face-font 'default "Kochi Mincho-14" nil '(lang-ja) 'append) | |
| 2565 ;; Oops, too sober. Try something to match AirCut. | |
| 2566 (set-face-font 'default "Mikachan-14" | |
| 2567 nil '(lang-ja) 'remove-tag-set-append) | |
| 2568 @end example | |
| 2569 | |
| 2570 The only way to configure widget fonts at the present time is to use X | |
| 2571 resources (or hack the source and rebuild). Currently supported widgets | |
| 2572 are | |
| 2573 @itemize | |
| 2574 @item | |
| 2575 menubars | |
| 2576 @item | |
| 2577 tab controls | |
| 2578 @end itemize | |
| 2579 | |
| 2580 Here are the resources I use. @strong{Warning:} @emph{This interface | |
| 2581 will change. Pay attention to beta announcements, and complain loudly | |
| 2582 if changes aren't documented here!} The tab control and menubar have | |
|
4666
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2583 separate @code{Font} and @code{FcFontName} resources, and use the X |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2584 resource manager to instantiate a FontStruct from the @code{Font} |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2585 resource. There is no converter facility for @code{FcFontName} yet, and |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2586 creating one that handles both FontStruct and XftFont depending on |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2587 XEmacs's configuration and the font name seems error-prone at best. |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2588 Probably we will use a simple string representation for this resource, |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2589 and convert to a face in XEmacs rather than a font in Xt/Xft. (The |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2590 older @code{XftFont} resource is deprecated. There is code intended to |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2591 implement backward compatibility, but there are repots that it doesn't |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2592 work properly.) |
| 3387 | 2593 @example |
|
4666
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2594 XEmacs*Tabs.fcFontName: Bitstream Vera Sans-16 |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2595 XEmacs*menubar*fcFontName: Bitstream Vera Sans-16 |
| 3387 | 2596 XEmacs.modeline.attributeFont: Bitstream Charter-16 |
| 2597 XEmacs.default.attributeFont: Bitstream Vera Sans Mono-16 | |
| 2598 @end example | |
| 2599 I highly recommend use of a proportional font in the modeline because it | |
| 2600 allows a lot more text to fit there. | |
| 2601 @c Previously the font sizes were quite varied, and there was a comment | |
| 2602 @c that this weirdness gave good balance. This isn't true on my main | |
| 2603 @c platform, Mac OS X, and needs to be rechecked on Linux, where it was | |
| 2604 @c observed. | |
| 2605 | |
| 2606 @subheading Known Problems | |
| 2607 | |
| 2608 @table @code | |
| 2609 @item Options->Font | |
| 2610 @itemx Options->Font Size | |
| 2611 These menus don't work. All fonts are greyed out. All sizes are | |
| 2612 available, but many (most?) faces don't change size, in particular, | |
| 2613 @samp{default} does not. | |
| 2614 | |
| 2615 @item Antialiased text bleeding outside of reported extent | |
| 2616 This is most obvious with the underscore character in that | |
| 2617 font, and with cursors. The bottom of the underscore is antialiased, | |
| 2618 and insertions or deletions in the same line before the underscore leave | |
| 2619 a series of "phantom" underlines. | |
| 2620 | |
| 2621 I think this is probably an Xft bug, but I'm not sure. | |
| 2622 @end table | |
| 2623 | |
| 2624 @subheading Variables Used with Xft and Fontconfig | |
| 2625 | |
| 2626 @defvar xft-debug-level | |
| 2627 | |
| 2628 Level of debugging messages to issue to stderr for @var{Xft}. | |
| 2629 A nonnegative integer. Set to 0 to suppress all warnings. | |
| 2630 Default is 1 to ensure a minimum of debugging output at initialization. | |
| 2631 Higher levels give more information. | |
| 2632 @end defvar | |
| 2633 | |
| 2634 @defvar xft-version | |
| 2635 | |
| 2636 The major version number of the Xft library compiled with. | |
| 2637 @end defvar | |
| 2638 | |
| 2639 @defvar xft-xlfd-font-regexp | |
| 2640 | |
| 2641 Regular expression matching XLFD font names. | |
| 2642 @end defvar | |
| 2643 | |
| 2644 | |
| 442 | 2645 @node Frame Components |
| 2646 @section Frame Components | |
| 2647 | |
| 2648 You can control the presence and position of most frame components, such | |
| 2649 as the menubar, toolbars, and gutters. | |
| 2650 | |
| 2651 This section is not written yet. Try the Lisp Reference Manual: | |
| 2652 @ref{Menubar,,,lispref,}, @ref{Toolbar Intro,,,lispref,}, and | |
| 2653 @ref{Gutter Intro,,,lispref,}. | |
| 2654 | |
| 428 | 2655 @node X Resources |
| 2656 @section X Resources | |
| 2657 @cindex X resources | |
| 2658 @findex x-create-frame | |
| 2659 | |
| 2681 | 2660 Historically, XEmacs used the X resource application class @samp{Emacs} |
| 2736 | 2661 for its resources. Unfortunately, GNU Emacs's usage of resources has |
| 2662 evolved differently from XEmacs's, and especially in the case of fonts | |
| 2663 semantics are not compatible between the two Emacsen. Thus, sharing of | |
| 2664 the application class can easily lead to trouble. | |
| 428 | 2665 |
| 2681 | 2666 XEmacs now uses the X resource application class @samp{XEmacs}. |
| 2736 | 2667 Versions since 21.5.21 do this unconditionally. To attempt to maintain |
| 2668 some backward compatibility, previous versions checked the X resource | |
| 2669 database for resources starting in @samp{XEmacs}, and if none were | |
| 2670 found, @samp{Emacs} was used. This behavior is likely to be obsoleted, | |
| 2671 so you should move your X resources to using the @samp{XEmacs} class. | |
| 2672 In the short term, to stay with the old behavior, start XEmacs with the | |
| 2673 environment variable @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} set to | |
| 2674 some non-empty value; this will restore the pre-21.5.21 behavior. | |
| 2675 @c #### is this documented in the Lispref? | |
| 2676 Lisp programs can examine the variable @code{x-emacs-application-class} | |
| 2677 to determine which is being used in the running application. | |
| 2681 | 2678 |
| 2679 The examples in this section assume the application class is | |
| 2736 | 2680 @samp{XEmacs}. |
| 2681 | |
| 2682 Most of XEmacs's resources are set per-frame. Each XEmacs frame can | |
| 2681 | 2683 have its own name or the same name as another, depending on the name |
| 2684 passed to the @code{make-frame} function. Up until 21.5.21, the default | |
| 2685 frame name was @samp{emacs}; since then, it has been @samp{XEmacs}, but | |
| 2686 in the short term the old default can be restored by the | |
| 2687 @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} environment variable | |
| 2736 | 2688 mentioned above. |
| 2689 @c #### Cheesy. Variable should be documented here. | |
| 2690 See the docstring for the Lisp variable `default-frame-name'. | |
| 428 | 2691 |
| 2692 You can specify resources for all frames with the syntax: | |
| 2693 | |
| 2694 @example | |
| 2681 | 2695 XEmacs*parameter: value |
| 428 | 2696 @end example |
| 2697 @noindent | |
| 2698 | |
| 2699 or | |
| 2700 | |
| 2701 @example | |
| 2681 | 2702 XEmacs*EmacsFrame.parameter:value |
| 428 | 2703 @end example |
| 2704 @noindent | |
| 2705 | |
| 2706 You can specify resources for a particular frame with the syntax: | |
| 2707 | |
| 2708 @example | |
| 2681 | 2709 XEmacs*FRAME-NAME.parameter: value |
| 428 | 2710 @end example |
| 2711 @noindent | |
| 2712 | |
| 2713 @menu | |
| 2714 * Geometry Resources:: Controlling the size and position of frames. | |
| 440 | 2715 * Iconic Resources:: Controlling whether frames come up iconic. |
| 2716 * Resource List:: List of resources settable on a frame or device. | |
| 2717 * Face Resources:: Controlling faces using resources. | |
| 2718 * Widgets:: The widget hierarchy for XEmacs. | |
| 2719 * Menubar Resources:: Specifying resources for the menubar. | |
| 428 | 2720 @end menu |
| 2721 | |
| 2722 @node Geometry Resources | |
| 2723 @subsection Geometry Resources | |
| 2724 | |
| 2681 | 2725 To make the default size of all XEmacs frames be 80 columns by 55 lines, |
| 428 | 2726 do this: |
| 2727 | |
| 2728 @example | |
| 2681 | 2729 XEmacs*EmacsFrame.geometry: 80x55 |
| 428 | 2730 @end example |
| 2731 @noindent | |
| 2732 | |
| 2733 To set the geometry of a particular frame named @samp{fred}, do this: | |
| 2734 | |
| 2735 @example | |
| 2681 | 2736 XEmacs*fred.geometry: 80x55 |
| 428 | 2737 @end example |
| 2738 @noindent | |
| 2739 | |
| 2740 Important! Do not use the following syntax: | |
| 2741 | |
| 2742 @example | |
| 2681 | 2743 XEmacs*geometry: 80x55 |
| 428 | 2744 @end example |
| 2745 @noindent | |
| 2746 | |
| 2747 You should never use @code{*geometry} with any X application. It does | |
| 2681 | 2748 not say "make the geometry of XEmacs be 80 columns by 55 lines." It |
| 2749 really says, "make XEmacs and all subwindows thereof be 80x55 in whatever | |
| 428 | 2750 units they care to measure in." In particular, that is both telling the |
| 2681 | 2751 XEmacs text pane to be 80x55 in characters, and telling the menubar pane |
| 428 | 2752 to be 80x55 pixels, which is surely not what you want. |
| 2753 | |
| 2754 As a special case, this geometry specification also works (and sets the | |
| 2681 | 2755 default size of all XEmacs frames to 80 columns by 55 lines): |
| 428 | 2756 |
| 2757 @example | |
| 2681 | 2758 XEmacs.geometry: 80x55 |
| 428 | 2759 @end example |
| 2760 @noindent | |
| 2761 | |
| 2762 since that is the syntax used with most other applications (since most | |
| 2681 | 2763 other applications have only one top-level window, unlike XEmacs). In |
| 428 | 2764 general, however, the top-level shell (the unmapped ApplicationShell |
| 2681 | 2765 widget named @samp{XEmacs} that is the parent of the shell widgets that |
| 428 | 2766 actually manage the individual frames) does not have any interesting |
| 2767 resources on it, and you should set the resources on the frames instead. | |
| 2768 | |
| 2769 The @code{-geometry} command-line argument sets only the geometry of the | |
| 2681 | 2770 initial frame created by XEmacs. |
| 428 | 2771 |
| 2772 A more complete explanation of geometry-handling is | |
| 2773 | |
| 2774 @itemize @bullet | |
| 2775 @item | |
| 2681 | 2776 The @code{-geometry} command-line option sets the @code{XEmacs.geometry} |
| 428 | 2777 resource, that is, the geometry of the ApplicationShell. |
| 2778 | |
| 2779 @item | |
| 2780 For the first frame created, the size of the frame is taken from the | |
| 2781 ApplicationShell if it is specified, otherwise from the geometry of the | |
| 2782 frame. | |
| 2783 | |
| 2784 @item | |
| 2785 For subsequent frames, the order is reversed: First the frame, and then | |
| 2786 the ApplicationShell. | |
| 2787 | |
| 2788 @item | |
| 2789 For the first frame created, the position of the frame is taken from the | |
| 2681 | 2790 ApplicationShell (@code{XEmacs.geometry}) if it is specified, otherwise |
| 428 | 2791 from the geometry of the frame. |
| 2792 | |
| 2793 @item | |
| 1137 | 2794 For subsequent frames, the position is taken only from the frame, and |
| 428 | 2795 never from the ApplicationShell. |
| 2796 @end itemize | |
| 2797 | |
| 2798 This is rather complicated, but it does seem to provide the most | |
| 2799 intuitive behavior with respect to the default sizes and positions of | |
| 2800 frames created in various ways. | |
| 2801 | |
| 2802 @node Iconic Resources | |
| 2803 @subsection Iconic Resources | |
| 2804 | |
| 2805 Analogous to @code{-geometry}, the @code{-iconic} command-line option | |
| 2681 | 2806 sets the iconic flag of the ApplicationShell (@code{XEmacs.iconic}) and |
| 428 | 2807 always applies to the first frame created regardless of its name. |
| 2808 However, it is possible to set the iconic flag on particular frames (by | |
| 2681 | 2809 name) by using the @code{XEmacs*FRAME-NAME.iconic} resource. |
| 428 | 2810 |
| 2811 @node Resource List | |
| 2812 @subsection Resource List | |
| 2813 | |
| 2681 | 2814 XEmacs frames accept the following resources: |
| 428 | 2815 |
| 2816 @table @asis | |
| 2817 @item @code{geometry} (class @code{Geometry}): string | |
| 2818 Initial geometry for the frame. @xref{Geometry Resources}, for a | |
| 2819 complete discussion of how this works. | |
| 2820 | |
| 2821 @item @code{iconic} (class @code{Iconic}): boolean | |
| 2822 Whether this frame should appear in the iconified state. | |
| 2823 | |
| 2824 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int | |
| 1137 | 2825 How many blank pixels to leave between the text and the edge of the |
| 428 | 2826 window. |
| 2827 | |
| 2828 @item @code{interline} (class @code{Interline}): int | |
| 2829 How many pixels to leave between each line (may not be implemented). | |
| 2830 | |
| 2831 @item @code{menubar} (class @code{Menubar}): boolean | |
| 2832 Whether newly-created frames should initially have a menubar. Set to | |
| 2833 true by default. | |
| 2834 | |
| 2835 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean | |
| 2836 Whether XEmacs should leave the initial frame unmapped when it starts | |
| 2837 up. This is useful if you are starting XEmacs as a server (e.g. in | |
| 2838 conjunction with gnuserv or the external client widget). You can also | |
| 2839 control this with the @code{-unmapped} command-line option. | |
| 2840 | |
| 2841 @item @code{barCursor} (class @code{BarColor}): boolean | |
| 2842 Whether the cursor should be displayed as a bar, or the traditional box. | |
| 2843 | |
| 2844 @item @code{cursorColor} (class @code{CursorColor}): color-name | |
| 2845 The color of the text cursor. | |
| 2846 | |
| 2847 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer | |
| 2848 How wide the vertical scrollbars should be, in pixels; 0 means no | |
| 2849 vertical scrollbars. You can also use a resource specification of the | |
| 2850 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources: | |
| 2851 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid), | |
| 2852 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you | |
| 2853 use the toolkit resources, though, because they're dependent on how | |
| 2854 exactly your particular build of XEmacs was configured. | |
| 2855 | |
| 2856 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer | |
| 2857 How high the horizontal scrollbars should be, in pixels; 0 means no | |
| 2858 horizontal scrollbars. You can also use a resource specification of the | |
| 2859 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources: | |
| 2860 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid), | |
| 2861 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you use | |
| 2862 the toolkit resources, though, because they're dependent on how exactly | |
| 2863 your particular build of XEmacs was configured. | |
| 2864 | |
| 2865 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string | |
| 2866 Where the horizontal and vertical scrollbars should be positioned. This | |
| 2867 should be one of the four strings @samp{BOTTOM_LEFT}, | |
| 2868 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}. Default is | |
| 2869 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and | |
| 2870 @samp{BOTTOM_LEFT} for the Athena scrollbars. | |
| 2871 | |
| 2872 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer | |
| 2873 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer | |
| 2874 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer | |
| 2875 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer | |
| 2876 Height and width of the four possible toolbars. | |
| 2877 | |
| 2878 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name | |
| 2879 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name | |
| 2880 Color of the top and bottom shadows for the toolbars. NOTE: These resources | |
| 2881 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the | |
| 2882 toolbars at the top and bottom of the frame)! Rather, they affect the top | |
| 2883 and bottom shadows around the edges of all four kinds of toolbars. | |
| 2884 | |
| 2885 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name | |
| 2886 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name | |
| 2887 Pixmap of the top and bottom shadows for the toolbars. If set, these | |
| 2888 resources override the corresponding color resources. NOTE: These | |
| 2889 resources do @emph{not} have anything to do with the top and bottom | |
| 2890 toolbars (i.e. the toolbars at the top and bottom of the frame)! | |
| 2891 Rather, they affect the top and bottom shadows around the edges of all | |
| 2892 four kinds of toolbars. | |
| 2893 | |
| 2894 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer | |
| 2895 Thickness of the shadows around the toolbars, in pixels. | |
| 2896 | |
| 2897 @item @code{visualBell} (class @code{VisualBell}): boolean | |
| 2898 Whether XEmacs should flash the screen rather than making an audible beep. | |
| 2899 | |
| 2900 @item @code{bellVolume} (class @code{BellVolume}): integer | |
| 2901 Volume of the audible beep. | |
| 2902 | |
| 2903 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean | |
| 2904 Whether XEmacs should set the backing-store attribute of the X windows | |
| 2905 it creates. This increases the memory usage of the X server but decreases | |
| 2906 the amount of X traffic necessary to update the screen, and is useful | |
| 2907 when the connection to the X server goes over a low-bandwidth line | |
| 2908 such as a modem connection. | |
| 2909 @end table | |
| 2910 | |
| 2681 | 2911 XEmacs devices accept the following resources: |
| 428 | 2912 |
| 2913 @table @asis | |
| 2914 @item @code{textPointer} (class @code{Cursor}): cursor-name | |
| 2915 The cursor to use when the mouse is over text. This resource is used to | |
| 2916 initialize the variable @code{x-pointer-shape}. | |
| 2917 | |
| 2918 @item @code{selectionPointer} (class @code{Cursor}): cursor-name | |
| 2919 The cursor to use when the mouse is over a selectable text region (an | |
| 2920 extent with the @samp{highlight} property; for example, an Info | |
| 2921 cross-reference). This resource is used to initialize the variable | |
| 2922 @code{x-selection-pointer-shape}. | |
| 2923 | |
| 2924 @item @code{spacePointer} (class @code{Cursor}): cursor-name | |
| 2925 The cursor to use when the mouse is over a blank space in a buffer (that | |
| 2926 is, after the end of a line or after the end-of-file). This resource is | |
| 2927 used to initialize the variable @code{x-nontext-pointer-shape}. | |
| 2928 | |
| 2929 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name | |
| 2930 The cursor to use when the mouse is over a modeline. This resource is | |
| 2931 used to initialize the variable @code{x-mode-pointer-shape}. | |
| 2932 | |
| 2933 @item @code{gcPointer} (class @code{Cursor}): cursor-name | |
| 2934 The cursor to display when a garbage-collection is in progress. This | |
| 2935 resource is used to initialize the variable @code{x-gc-pointer-shape}. | |
| 2936 | |
| 2937 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name | |
| 2938 The cursor to use when the mouse is over the scrollbar. This resource | |
| 2939 is used to initialize the variable @code{x-scrollbar-pointer-shape}. | |
| 2940 | |
| 2941 @item @code{pointerColor} (class @code{Foreground}): color-name | |
| 2942 @itemx @code{pointerBackground} (class @code{Background}): color-name | |
| 2943 The foreground and background colors of the mouse cursor. These | |
| 2944 resources are used to initialize the variables | |
| 2945 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}. | |
| 2946 @end table | |
| 2947 | |
| 2948 @node Face Resources | |
| 2949 @subsection Face Resources | |
| 2950 | |
| 2951 The attributes of faces are also per-frame. They can be specified as: | |
| 2952 | |
| 2953 @example | |
| 2681 | 2954 XEmacs.FACE_NAME.parameter: value |
| 428 | 2955 @end example |
| 2956 @noindent | |
| 2957 | |
| 2958 or | |
| 2959 | |
| 2960 @example | |
| 2681 | 2961 XEmacs*FRAME_NAME.FACE_NAME.parameter: value |
| 428 | 2962 @end example |
| 2963 @noindent | |
| 2964 | |
| 2965 Faces accept the following resources: | |
| 2966 | |
| 2967 @table @asis | |
| 2968 @item @code{attributeFont} (class @code{AttributeFont}): font-name | |
| 2969 The font of this face. | |
| 2970 | |
| 2971 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name | |
| 2972 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name | |
| 2973 The foreground and background colors of this face. | |
| 2974 | |
| 2975 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name | |
| 2681 | 2976 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of XEmacs |
| 428 | 2977 supports @sc{xpm}), to use as a background stipple. |
| 2978 | |
| 2979 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean | |
| 2980 Whether text in this face should be underlined. | |
| 2981 @end table | |
| 2982 | |
| 2983 All text is displayed in some face, defaulting to the face named | |
| 2984 @code{default}. To set the font of normal text, use | |
| 2681 | 2985 @code{XEmacs*default.attributeFont}. To set it in the frame named |
| 2986 @code{fred}, use @code{XEmacs*fred.default.attributeFont}. | |
| 428 | 2987 |
| 2988 These are the names of the predefined faces: | |
| 2989 | |
| 2990 @table @code | |
| 2991 @item default | |
| 2992 Everything inherits from this. | |
| 2993 | |
| 2994 @item bold | |
| 2681 | 2995 If this is not specified in the resource database, XEmacs tries to find a |
| 428 | 2996 bold version of the font of the default face. |
| 2997 | |
| 2998 @item italic | |
| 2681 | 2999 If this is not specified in the resource database, XEmacs tries to find |
| 428 | 3000 an italic version of the font of the default face. |
| 3001 | |
| 3002 @item bold-italic | |
| 2681 | 3003 If this is not specified in the resource database, XEmacs tries to find a |
| 428 | 3004 bold-italic version of the font of the default face. |
| 3005 | |
| 3006 @item modeline | |
| 3007 This is the face that the modeline is displayed in. If not specified in | |
| 3008 the resource database, it is determined from the default face by | |
| 3009 reversing the foreground and background colors. | |
| 3010 | |
| 3011 @item highlight | |
| 3012 This is the face that highlighted extents (for example, Info | |
| 3013 cross-references and possible completions, when the mouse passes over | |
| 3014 them) are displayed in. | |
| 3015 | |
| 3016 @item left-margin | |
| 3017 @itemx right-margin | |
| 3018 These are the faces that the left and right annotation margins are | |
| 3019 displayed in. | |
| 3020 | |
| 3021 @item zmacs-region | |
| 3022 This is the face that mouse selections are displayed in. | |
| 1137 | 3023 |
| 428 | 3024 @item isearch |
| 3025 This is the face that the matched text being searched for is displayed | |
| 3026 in. | |
| 3027 | |
| 3028 @item info-node | |
| 3029 This is the face of info menu items. If unspecified, it is copied from | |
| 3030 @code{bold-italic}. | |
| 3031 | |
| 3032 @item info-xref | |
| 3033 This is the face of info cross-references. If unspecified, it is copied | |
| 3034 from @code{bold}. (Note that, when the mouse passes over a | |
| 3035 cross-reference, the cross-reference's face is determined from a | |
| 3036 combination of the @code{info-xref} and @code{highlight} faces.) | |
| 3037 @end table | |
| 3038 | |
| 3039 Other packages might define their own faces; to see a list of all faces, | |
| 3040 use any of the interactive face-manipulation commands such as | |
| 3041 @code{set-face-font} and type @samp{?} when you are prompted for the | |
| 3042 name of a face. | |
| 3043 | |
| 3044 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not | |
| 3045 specified in the resource database, then XEmacs attempts to derive them | |
| 3046 from the font of the default face. It can only succeed at this if you | |
| 3047 have specified the default font using the XLFD (X Logical Font | |
| 3048 Description) format, which looks like | |
| 3049 | |
| 3050 @example | |
| 3051 *-courier-medium-r-*-*-*-120-*-*-*-*-*-* | |
| 3052 @end example | |
| 3053 @noindent | |
| 3054 | |
| 3711 | 3055 All X fonts can be referred to via XLFD-style names, and you should use |
| 3056 those forms. See the man pages for @samp{X(1)}, @samp{xlsfonts(1)}, and | |
| 3057 @samp{xfontsel(1)}. | |
| 3058 | |
| 428 | 3059 If you use any of the other, less strict font name formats, some of which |
| 3060 look like | |
| 3061 | |
| 3062 @example | |
| 3063 lucidasanstypewriter-12 | |
| 3064 fixed | |
| 3065 9x13 | |
| 3066 @end example | |
| 3067 | |
| 3068 then XEmacs won't be able to guess the names of the bold and italic | |
| 3711 | 3069 versions, and on a build with internationalization support, it will |
| 3070 refuse to use them. (Since only the XLFD form includes information as | |
| 3071 to which character set the font coverage.) | |
| 3072 | |
| 3073 If it is very important to you to use the short form names, you can | |
| 3074 override this for ASCII, and for ASCII alone, by passing the | |
| 3075 @samp{FORCE} argument to @samp{set-charset-registries}, and specifying | |
| 3076 an empty string as one of the charset registries. | |
| 428 | 3077 |
| 3078 @node Widgets | |
| 3079 @subsection Widgets | |
| 3080 | |
| 3081 There are several structural widgets between the terminal EmacsFrame | |
| 3082 widget and the top level ApplicationShell; the exact names and types of | |
| 3083 these widgets change from release to release (for example, they changed | |
| 3084 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are | |
| 3085 subject to further change in the future, so you should avoid mentioning | |
| 3086 them in your resource database. The above-mentioned syntaxes should be | |
| 3087 forward- compatible. As of 19.13, the exact widget hierarchy is as | |
| 3088 follows: | |
| 3089 | |
| 3090 @example | |
| 3091 INVOCATION-NAME "shell" "container" FRAME-NAME | |
| 3092 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame" | |
| 3093 @end example | |
| 3094 | |
| 3095 where INVOCATION-NAME is the terminal component of the name of the | |
| 3096 XEmacs executable (usually @samp{xemacs}), and | |
| 2736 | 3097 @samp{x-emacs-application-class} is generally @samp{XEmacs}. |
| 428 | 3098 |
| 3099 @node Menubar Resources | |
| 3100 @subsection Menubar Resources | |
| 3101 | |
| 3102 As the menubar is implemented as a widget which is not a part of XEmacs | |
| 442 | 3103 proper, it does not use the face mechanism for specifying fonts and |
| 428 | 3104 colors: It uses whatever resources are appropriate to the type of widget |
| 3105 which is used to implement it. | |
| 3106 | |
| 2681 | 3107 If XEmacs was compiled to use only the Lucid Motif-lookalike menu widgets, |
| 442 | 3108 then one way to specify the font of the menubar would be |
| 428 | 3109 |
| 3110 @example | |
| 2681 | 3111 XEmacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* |
| 428 | 3112 @end example |
| 3113 | |
| 1137 | 3114 If both the Lucid Motif-lookalike menu widgets and X Font Sets are |
| 442 | 3115 configured to allow multilingual menubars, then one uses |
| 3116 | |
| 3117 @example | |
| 3118 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \ | |
| 3119 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0 | |
| 3120 @end example | |
| 3121 | |
| 3122 That would specify fonts for a Japanese menubar. Specifying only one | |
| 3123 XLFD is acceptable; specifying more than one for a given registry | |
| 3124 (language) is also allowed. When X Font Sets are configured, some .font | |
| 3125 resources (eg, menubars) are ignored in favor of the corresponding | |
| 3126 .fontSet resources. | |
| 3127 | |
| 1137 | 3128 If the Motif library is being used, then one would have to use |
| 428 | 3129 |
| 3130 @example | |
| 2681 | 3131 XEmacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* |
| 428 | 3132 @end example |
| 3133 | |
| 3134 because the Motif library uses the @code{fontList} resource name instead | |
| 3135 of @code{font}, which has subtly different semantics. | |
| 3136 | |
| 1137 | 3137 The same is true of the scrollbars: They accept whichever resources are |
| 428 | 3138 appropriate for the toolkit in use. |