Mercurial > emacs
comparison man/custom.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 23a1cea22d13 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c This is part of the Emacs manual. | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002 | 2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
3 @c Free Software Foundation, Inc. | 3 @c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. |
4 @c See file emacs.texi for copying conditions. | 4 @c See file emacs.texi for copying conditions. |
5 @node Customization, Quitting, Amusements, Top | 5 @node Customization, Quitting, Amusements, Top |
6 @chapter Customization | 6 @chapter Customization |
7 @cindex customization | 7 @cindex customization |
8 | 8 |
9 This chapter talks about various topics relevant to adapting the | 9 This chapter talks about various topics relevant to adapting the |
10 behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference | 10 behavior of Emacs in minor ways. |
11 Manual} for how to make more far-reaching changes. @xref{X Resources}, | 11 @iftex |
12 See @cite{The Emacs Lisp Reference Manual} | |
13 @end iftex | |
14 @ifnottex | |
15 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp | |
16 Reference Manual}, | |
17 @end ifnottex | |
18 for how to make more far-reaching changes. @xref{X Resources}, | |
12 for information on using X resources to customize Emacs. | 19 for information on using X resources to customize Emacs. |
13 | 20 |
14 Customization that you do within Emacs normally affects only the | 21 Customization that you do within Emacs normally affects only the |
15 particular Emacs session that you do it in--it does not persist | 22 particular Emacs session that you do it in---it does not persist |
16 between sessions unless you save the customization in a file such as | 23 between sessions unless you save the customization in a file such as |
17 @file{.emacs} or @file{.Xdefaults} that will affect future sessions. | 24 @file{.emacs} or @file{.Xdefaults} that will affect future sessions. |
18 @xref{Init File}. In the customization buffer, when you save | 25 @xref{Init File}. In the customization buffer, when you save |
19 customizations for future sessions, this actually works by editing | 26 customizations for future sessions, this actually works by editing |
20 @file{.emacs} for you. | 27 @file{.emacs} for you. |
21 | 28 |
29 Another means of customization is the keyboard macro, which is a | |
30 sequence of keystrokes to be replayed with a single command. | |
31 @xref{Keyboard Macros}, for full instruction how to record, manage, and | |
32 replay sequences of keys. | |
33 | |
22 @menu | 34 @menu |
23 * Minor Modes:: Each minor mode is one feature you can turn on | 35 * Minor Modes:: Each minor mode is one feature you can turn on |
24 independently of any others. | 36 independently of any others. |
37 * Easy Customization:: Convenient way to browse and change settings. | |
25 * Variables:: Many Emacs commands examine Emacs variables | 38 * Variables:: Many Emacs commands examine Emacs variables |
26 to decide what to do; by setting variables, | 39 to decide what to do; by setting variables, |
27 you can control their functioning. | 40 you can control their functioning. |
28 * Keyboard Macros:: A keyboard macro records a sequence of | |
29 keystrokes to be replayed with a single | |
30 command. | |
31 * Key Bindings:: The keymaps say what command each key runs. | 41 * Key Bindings:: The keymaps say what command each key runs. |
32 By changing them, you can "redefine keys". | 42 By changing them, you can "redefine keys". |
33 * Keyboard Translations:: | |
34 If your keyboard passes an undesired code | |
35 for a key, you can tell Emacs to | |
36 substitute another code. | |
37 * Syntax:: The syntax table controls how words and | 43 * Syntax:: The syntax table controls how words and |
38 expressions are parsed. | 44 expressions are parsed. |
39 * Init File:: How to write common customizations in the | 45 * Init File:: How to write common customizations in the |
40 @file{.emacs} file. | 46 @file{.emacs} file. |
41 @end menu | 47 @end menu |
42 | 48 |
43 @node Minor Modes | 49 @node Minor Modes |
51 other and of the selected major mode. Most minor modes say in the mode | 57 other and of the selected major mode. Most minor modes say in the mode |
52 line when they are on; for example, @samp{Fill} in the mode line means | 58 line when they are on; for example, @samp{Fill} in the mode line means |
53 that Auto Fill mode is on. | 59 that Auto Fill mode is on. |
54 | 60 |
55 Append @code{-mode} to the name of a minor mode to get the name of a | 61 Append @code{-mode} to the name of a minor mode to get the name of a |
56 command function that turns the mode on or off. Thus, the command to | 62 command that turns the mode on or off. Thus, the command to |
57 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These | 63 enable or disable Auto Fill mode is called @code{auto-fill-mode}. These |
58 commands are usually invoked with @kbd{M-x}, but you can bind keys to them | 64 commands are usually invoked with @kbd{M-x}, but you can bind keys to them |
59 if you wish. With no argument, the function turns the mode on if it was | 65 if you wish. With no argument, the function turns the mode on if it was |
60 off and off if it was on. This is known as @dfn{toggling}. A positive | 66 off and off if it was on. This is known as @dfn{toggling}. A positive |
61 argument always turns the mode on, and an explicit zero argument or a | 67 argument always turns the mode on, and an explicit zero argument or a |
62 negative argument always turns it off. | 68 negative argument always turns it off. |
65 you do in the Emacs session, in all buffers. Other minor modes are | 71 you do in the Emacs session, in all buffers. Other minor modes are |
66 buffer-local; they apply only to the current buffer, so you can enable | 72 buffer-local; they apply only to the current buffer, so you can enable |
67 the mode in certain buffers and not others. | 73 the mode in certain buffers and not others. |
68 | 74 |
69 For most minor modes, the command name is also the name of a | 75 For most minor modes, the command name is also the name of a |
70 variable which directly controls the mode. The mode is enabled | 76 variable. The variable's value is non-@code{nil} if the mode is |
71 whenever this variable's value is non-@code{nil}, and the minor-mode | 77 enabled and @code{nil} if it is disabled. Some minor-mode commands |
72 command works by setting the variable. For example, the command | 78 work by just setting the variable. For example, the command |
73 @code{outline-minor-mode} works by setting the value of | 79 @code{abbrev-mode} works by setting the value of @code{abbrev-mode} as |
74 @code{outline-minor-mode} as a variable; it is this variable that | 80 a variable; it is this variable that directly turns Abbrev mode on and |
75 directly turns Outline minor mode on and off. To check whether a | 81 off. You can directly set the variable's value instead of calling the |
76 given minor mode works this way, use @kbd{C-h v} to ask for | 82 mode function. For other minor modes, you need to either set the |
77 documentation on the variable name. | 83 variable through the Customize interface or call the mode function to |
78 | 84 correctly enable or disable the mode. To check which of these two |
79 These minor-mode variables provide a good way for Lisp programs to turn | 85 possibilities applies to a given minor mode, use @kbd{C-h v} to ask |
80 minor modes on and off; they are also useful in a file's local variables | 86 for documentation on the variable name. |
81 list. But please think twice before setting minor modes with a local | 87 |
82 variables list, because most minor modes are matter of user | 88 For minor mode commands that work by just setting the minor mode |
83 preference---other users editing the same file might not want the same | 89 variable, that variable provides a good way for Lisp programs to turn |
84 minor modes you prefer. | 90 minor modes on and off; it is also useful in a file's local variables |
85 | 91 list (@pxref{File Variables}). But please think twice before setting |
86 The buffer-local minor modes include Abbrev mode, Auto Fill mode, | 92 minor modes with a local variables list, because most minor modes are |
87 Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode, | 93 a matter of user preference---other users editing the same file might |
88 Outline minor mode, Overwrite mode, and Binary Overwrite mode. | 94 not want the same minor modes you prefer. |
95 | |
96 The most useful buffer-local minor modes include Abbrev mode, Auto | |
97 Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents | |
98 mode, Outline minor mode, Overwrite mode, and Binary Overwrite mode. | |
89 | 99 |
90 Abbrev mode allows you to define abbreviations that automatically expand | 100 Abbrev mode allows you to define abbreviations that automatically expand |
91 as you type them. For example, @samp{amd} might expand to @samp{abbrev | 101 as you type them. For example, @samp{amd} might expand to @samp{abbrev |
92 mode}. @xref{Abbrevs}, for full information. | 102 mode}. @xref{Abbrevs}, for full information. |
93 | 103 |
142 binary files; it treats newlines and tabs like other characters, so that | 152 binary files; it treats newlines and tabs like other characters, so that |
143 they overwrite other characters and can be overwritten by them. | 153 they overwrite other characters and can be overwritten by them. |
144 In Binary Overwrite mode, digits after @kbd{C-q} specify an | 154 In Binary Overwrite mode, digits after @kbd{C-q} specify an |
145 octal character code, as usual. | 155 octal character code, as usual. |
146 | 156 |
147 The following minor modes normally apply to all buffers at once. | 157 Here are some useful minor modes that normally apply to all buffers |
148 Since each is enabled or disabled by the value of a variable, you | 158 at once. Since Line Number mode and Transient Mark mode can be |
149 @emph{can} set them differently for particular buffers, by explicitly | 159 enabled or disabled just by setting the value of the minor mode |
150 making the corresponding variables local in those buffers. | 160 variable, you @emph{can} set them differently for particular buffers, |
151 @xref{Locals}. | 161 by explicitly making the corresponding variable local in those |
162 buffers. @xref{Locals}. | |
152 | 163 |
153 Icomplete mode displays an indication of available completions when | 164 Icomplete mode displays an indication of available completions when |
154 you are in the minibuffer and completion is active. @xref{Completion | 165 you are in the minibuffer and completion is active. @xref{Completion |
155 Options}. | 166 Options}. |
156 | 167 |
165 In Transient Mark mode, every change in the buffer contents | 176 In Transient Mark mode, every change in the buffer contents |
166 ``deactivates'' the mark, so that commands that operate on the region | 177 ``deactivates'' the mark, so that commands that operate on the region |
167 will get an error. This means you must either set the mark, or | 178 will get an error. This means you must either set the mark, or |
168 explicitly ``reactivate'' it, before each command that uses the region. | 179 explicitly ``reactivate'' it, before each command that uses the region. |
169 The advantage of Transient Mark mode is that Emacs can display the | 180 The advantage of Transient Mark mode is that Emacs can display the |
170 region highlighted (currently only when using X). @xref{Mark}. | 181 region highlighted. @xref{Mark}. |
171 | |
172 @node Variables | |
173 @section Variables | |
174 @cindex variable | |
175 @cindex option, user | |
176 @cindex user option | |
177 | |
178 A @dfn{variable} is a Lisp symbol which has a value. The symbol's | |
179 name is also called the name of the variable. A variable name can | |
180 contain any characters that can appear in a file, but conventionally | |
181 variable names consist of words separated by hyphens. A variable can | |
182 have a documentation string which describes what kind of value it should | |
183 have and how the value will be used. | |
184 | |
185 Lisp allows any variable to have any kind of value, but most variables | |
186 that Emacs uses require a value of a certain type. Often the value should | |
187 always be a string, or should always be a number. Sometimes we say that a | |
188 certain feature is turned on if a variable is ``non-@code{nil},'' meaning | |
189 that if the variable's value is @code{nil}, the feature is off, but the | |
190 feature is on for @emph{any} other value. The conventional value to use to | |
191 turn on the feature---since you have to pick one particular value when you | |
192 set the variable---is @code{t}. | |
193 | |
194 Emacs uses many Lisp variables for internal record keeping, as any | |
195 Lisp program must, but the most interesting variables for you are the | |
196 ones that exist for the sake of customization. Emacs does not (usually) | |
197 change the values of these variables; instead, you set the values, and | |
198 thereby alter and control the behavior of certain Emacs commands. These | |
199 variables are called @dfn{user options}. Most user options are | |
200 documented in this manual, and appear in the Variable Index | |
201 (@pxref{Variable Index}). | |
202 | |
203 One example of a variable which is a user option is @code{fill-column}, which | |
204 specifies the position of the right margin (as a number of characters from | |
205 the left margin) to be used by the fill commands (@pxref{Filling}). | |
206 | |
207 @menu | |
208 * Examining:: Examining or setting one variable's value. | |
209 * Easy Customization:: | |
210 Convenient and easy customization of variables. | |
211 * Hooks:: Hook variables let you specify programs for parts | |
212 of Emacs to run on particular occasions. | |
213 * Locals:: Per-buffer values of variables. | |
214 * File Variables:: How files can specify variable values. | |
215 @end menu | |
216 | |
217 @node Examining | |
218 @subsection Examining and Setting Variables | |
219 @cindex setting variables | |
220 | |
221 @table @kbd | |
222 @item C-h v @var{var} @key{RET} | |
223 Display the value and documentation of variable @var{var} | |
224 (@code{describe-variable}). | |
225 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} | |
226 Change the value of variable @var{var} to @var{value}. | |
227 @end table | |
228 | |
229 To examine the value of a single variable, use @kbd{C-h v} | |
230 (@code{describe-variable}), which reads a variable name using the | |
231 minibuffer, with completion. It displays both the value and the | |
232 documentation of the variable. For example, | |
233 | |
234 @example | |
235 C-h v fill-column @key{RET} | |
236 @end example | |
237 | |
238 @noindent | |
239 displays something like this: | |
240 | |
241 @smallexample | |
242 fill-column's value is 70 | |
243 | |
244 Documentation: | |
245 *Column beyond which automatic line-wrapping should happen. | |
246 Automatically becomes buffer-local when set in any fashion. | |
247 @end smallexample | |
248 | |
249 @noindent | |
250 The star at the beginning of the documentation indicates that this | |
251 variable is a user option. @kbd{C-h v} is not restricted to user | |
252 options; it allows any variable name. | |
253 | |
254 @findex set-variable | |
255 The most convenient way to set a specific user option is with @kbd{M-x | |
256 set-variable}. This reads the variable name with the minibuffer (with | |
257 completion), and then reads a Lisp expression for the new value using | |
258 the minibuffer a second time. For example, | |
259 | |
260 @example | |
261 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
262 @end example | |
263 | |
264 @noindent | |
265 sets @code{fill-column} to 75. | |
266 | |
267 @kbd{M-x set-variable} is limited to user option variables, but you can | |
268 set any variable with a Lisp expression, using the function @code{setq}. | |
269 Here is a @code{setq} expression to set @code{fill-column}: | |
270 | |
271 @example | |
272 (setq fill-column 75) | |
273 @end example | |
274 | |
275 To execute an expression like this one, go to the @samp{*scratch*} | |
276 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp | |
277 Interaction}. | |
278 | |
279 Setting variables, like all means of customizing Emacs except where | |
280 otherwise stated, affects only the current Emacs session. | |
281 | 182 |
282 @node Easy Customization | 183 @node Easy Customization |
283 @subsection Easy Customization Interface | 184 @section Easy Customization Interface |
185 | |
186 @cindex settings | |
187 Emacs has many @dfn{settings} which have values that you can specify | |
188 in order to customize various commands. Many are documented in this | |
189 manual. Most settings are @dfn{user options}---that is to say, Lisp | |
190 variables (@pxref{Variables})---so their names appear in the Variable | |
191 Index (@pxref{Variable Index}). The other settings are faces and | |
192 their attributes (@pxref{Faces}). | |
284 | 193 |
285 @findex customize | 194 @findex customize |
286 @cindex customization buffer | 195 @cindex customization buffer |
287 A convenient way to find the user option variables that you want to | 196 You can browse interactively through settings and change them using |
288 change, and then change them, is with @kbd{M-x customize}. This | 197 @kbd{M-x customize}. This command creates a @dfn{customization |
289 command creates a @dfn{customization buffer} with which you can browse | 198 buffer}, which offers commands to navigate through a logically |
290 through the Emacs user options in a logically organized structure, | 199 organized structure of the Emacs settings; you can also use it to edit |
291 then edit and set their values. You can also use the customization | 200 and set their values, and to save settings permanently in your |
292 buffer to save settings permanently in your @file{~/.emacs} file | 201 @file{~/.emacs} file (@pxref{Init File}). |
293 (@pxref{Init File}). | 202 |
294 | 203 The appearance of the example buffers in this section is typically |
295 The appearance of the example buffers in the following is typically | 204 different under a window system, since faces are then used to indicate |
296 different under a window system where faces can be used to indicate the | 205 buttons and editable fields. |
297 active fields and other features. | |
298 | 206 |
299 @menu | 207 @menu |
300 * Groups: Customization Groups. | 208 * Groups: Customization Groups. How settings are classified in a structure. |
301 How options are classified in a structure. | 209 * Browsing: Browsing Custom. Browsing and searching for settings. |
302 * Changing an Option:: How to edit a value and set an option. | 210 * Changing a Variable:: How to edit an option's value and set the option. |
303 * Saving Customizations:: Details of saving customizations. | 211 * Saving Customizations:: Specifying the file for saving customizations. |
304 * Face Customization:: How to edit the attributes of a face. | 212 * Face Customization:: How to edit the attributes of a face. |
305 * Specific Customization:: Making a customization buffer for specific | 213 * Specific Customization:: Making a customization buffer for specific |
306 options, faces, or groups. | 214 variables, faces, or groups. |
215 * Custom Themes:: How to define collections of customized options | |
216 that can be loaded and unloaded together. | |
307 @end menu | 217 @end menu |
308 | 218 |
309 @node Customization Groups | 219 @node Customization Groups |
310 @subsubsection Customization Groups | 220 @subsection Customization Groups |
311 @cindex customization groups | 221 @cindex customization groups |
312 | 222 |
313 For customization purposes, user options are organized into | 223 For customization purposes, settings are organized into @dfn{groups} |
314 @dfn{groups} to help you find them. Groups are collected into bigger | 224 to help you find them. Groups are collected into bigger groups, all |
315 groups, all the way up to a master group called @code{Emacs}. | 225 the way up to a master group called @code{Emacs}. |
316 | 226 |
317 @kbd{M-x customize} creates a customization buffer that shows the | 227 @kbd{M-x customize} creates a customization buffer that shows the |
318 top-level @code{Emacs} group and the second-level groups immediately | 228 top-level @code{Emacs} group and the second-level groups immediately |
319 under it. It looks like this, in part: | 229 under it. It looks like this, in part: |
320 | 230 |
321 @smallexample | 231 @smallexample |
322 /- Emacs group: ---------------------------------------------------\ | 232 /- Emacs group: ---------------------------------------------------\ |
323 [State]: visible group members are all at standard settings. | 233 [State]: visible group members are all at standard values. |
324 Customization of the One True Editor. | 234 Customization of the One True Editor. |
325 See also [Manual]. | 235 See also [Manual]. |
326 | |
327 Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm | |
328 [State]: this option is unchanged from its standard setting. | |
329 How to ask for confirmation when leaving Emacs. [More] | |
330 | 236 |
331 Editing group: [Go to Group] | 237 Editing group: [Go to Group] |
332 Basic text editing facilities. | 238 Basic text editing facilities. |
333 | 239 |
334 External group: [Go to Group] | 240 External group: [Go to Group] |
347 @emph{their} contents are not included. Each group has a single-line | 253 @emph{their} contents are not included. Each group has a single-line |
348 documentation string; the @code{Emacs} group also has a @samp{[State]} | 254 documentation string; the @code{Emacs} group also has a @samp{[State]} |
349 line. | 255 line. |
350 | 256 |
351 @cindex editable fields (customization buffer) | 257 @cindex editable fields (customization buffer) |
352 @cindex active fields (customization buffer) | 258 @cindex buttons (customization buffer) |
353 Most of the text in the customization buffer is read-only, but it | 259 Most of the text in the customization buffer is read-only, but it |
354 typically includes some @dfn{editable fields} that you can edit. There | 260 typically includes some @dfn{editable fields} that you can edit. |
355 are also @dfn{active fields}; this means a field that does something | 261 There are also @dfn{buttons}, which do something when you @dfn{invoke} |
356 when you @dfn{invoke} it. To invoke an active field, either click on it | 262 them. To invoke a button, either click on it with @kbd{Mouse-1}, or |
357 with @kbd{Mouse-1}, or move point to it and type @key{RET}. | 263 move point to it and type @key{RET}. |
358 | 264 |
359 For example, the phrase @samp{[Go to Group]} that appears in a | 265 For example, the phrase @samp{[Go to Group]} that appears in a |
360 second-level group is an active field. Invoking the @samp{[Go to | 266 second-level group is a button. Invoking it creates a new |
361 Group]} field for a group creates a new customization buffer, which | 267 customization buffer, which shows that group and its contents. This |
362 shows that group and its contents. This field is a kind of hypertext | 268 is a kind of hypertext link to another group. |
363 link to another group. | 269 |
364 | 270 The @code{Emacs} group includes a few settings, but mainly it |
365 The @code{Emacs} group includes a few user options itself, but | 271 contains other groups, which contain more groups, which contain the |
366 mainly it contains other groups, which contain more groups, which | 272 settings. By browsing the hierarchy of groups, you will eventually |
367 contain the user options. By browsing the hierarchy of groups, you | 273 find the feature you are interested in customizing. Then you can use |
368 will eventually find the feature you are interested in customizing. | 274 the customization buffer to set that feature's settings. You can also |
369 Then you can use the customization buffer to set the options and faces | 275 go straight to a particular group by name, using the command @kbd{M-x |
370 pertaining to that feature. You can also go straight to a particular | 276 customize-group}. |
371 group by name, using the command @kbd{M-x customize-group}. | 277 |
372 | 278 @node Browsing Custom |
279 @subsection Browsing and Searching for Options and Faces | |
373 @findex customize-browse | 280 @findex customize-browse |
374 You can view the structure of customization groups on a larger scale | 281 |
375 with @kbd{M-x customize-browse}. This command creates a special kind of | 282 @kbd{M-x customize-browse} is another way to browse the available |
376 customization buffer which shows only the names of the groups (and | 283 settings. This command creates a special customization buffer which |
377 options and faces), and their structure. | 284 shows only the names of groups and settings, and puts them in a |
285 structure. | |
378 | 286 |
379 In this buffer, you can show the contents of a group by invoking | 287 In this buffer, you can show the contents of a group by invoking |
380 @samp{[+]}. When the group contents are visible, this button changes to | 288 @samp{[+]}. When the group contents are visible, this button changes to |
381 @samp{[-]}; invoking that hides the group contents. | 289 @samp{[-]}; invoking that hides the group contents. |
382 | 290 |
383 Each group, option or face name in this buffer has an active field | 291 Each setting in this buffer has a button which says @samp{[Group]}, |
384 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking | 292 @samp{[Option]} or @samp{[Face]}. Invoking this button creates an |
385 that active field creates an ordinary customization buffer showing just | 293 ordinary customization buffer showing just that group and its |
386 that group and its contents, just that option, or just that face. | 294 contents, just that user option, or just that face. This is the way |
387 This is the way to set values in it. | 295 to change settings that you find with @kbd{M-x customize-browse}. |
388 | 296 |
389 @node Changing an Option | 297 If you can guess part of the name of the settings you are interested |
390 @subsubsection Changing an Option | 298 in, @kbd{M-x customize-apropos} is another way to search for settings. |
391 | 299 However, unlike @code{customize} and @code{customize-browse}, |
392 Here is an example of what a user option looks like in the | 300 @code{customize-apropos} can only find groups and settings that are |
393 customization buffer: | 301 loaded in the current Emacs session. @xref{Specific Customization,, |
302 Customizing Specific Items}. | |
303 | |
304 @node Changing a Variable | |
305 @subsection Changing a Variable | |
306 | |
307 Here is an example of what a variable (a user option) looks like in | |
308 the customization buffer: | |
394 | 309 |
395 @smallexample | 310 @smallexample |
396 Kill Ring Max: [Hide] 60 | 311 Kill Ring Max: [Hide Value] 60 |
397 [State]: this option is unchanged from its standard setting. | 312 [State]: STANDARD. |
398 Maximum length of kill ring before oldest elements are thrown away. | 313 Maximum length of kill ring before oldest elements are thrown away. |
399 @end smallexample | 314 @end smallexample |
400 | 315 |
401 The text following @samp{[Hide]}, @samp{60} in this case, indicates | 316 The text following @samp{[Hide Value]}, @samp{60} in this case, indicates |
402 the current value of the option. If you see @samp{[Show]} instead of | 317 the current value of the variable. If you see @samp{[Show Value]} instead of |
403 @samp{[Hide]}, it means that the value is hidden; the customization | 318 @samp{[Hide Value]}, it means that the value is hidden; the customization |
404 buffer initially hides values that take up several lines. Invoke | 319 buffer initially hides values that take up several lines. Invoke |
405 @samp{[Show]} to show the value. | 320 @samp{[Show Value]} to show the value. |
406 | 321 |
407 The line after the option name indicates the @dfn{customization state} | 322 The line after the variable name indicates the @dfn{customization |
408 of the option: in the example above, it says you have not changed the | 323 state} of the variable: in the example above, it says you have not |
409 option yet. The word @samp{[State]} at the beginning of this line is | 324 changed the option yet. The @samp{[State]} button at the beginning of |
410 active; you can get a menu of various operations by invoking it with | 325 this line gives you a menu of various operations for customizing the |
411 @kbd{Mouse-1} or @key{RET}. These operations are essential for | 326 variable. |
412 customizing the variable. | |
413 | 327 |
414 The line after the @samp{[State]} line displays the beginning of the | 328 The line after the @samp{[State]} line displays the beginning of the |
415 option's documentation string. If there are more lines of | 329 variable's documentation string. If there are more lines of |
416 documentation, this line ends with @samp{[More]}; invoke this to show | 330 documentation, this line ends with a @samp{[More]} button; invoke that |
417 the full documentation string. | 331 to show the full documentation string. |
418 | 332 |
419 To enter a new value for @samp{Kill Ring Max}, move point to the value | 333 To enter a new value for @samp{Kill Ring Max}, move point to the |
420 and edit it textually. For example, you can type @kbd{M-d}, then insert | 334 value and edit it textually. For example, you can type @kbd{M-d}, |
421 another number. | 335 then insert another number. As you begin to alter the text, you will |
422 | 336 see the @samp{[State]} line change to say that you have edited the |
423 When you begin to alter the text, you will see the @samp{[State]} line | 337 value: |
424 change to say that you have edited the value: | |
425 | 338 |
426 @smallexample | 339 @smallexample |
427 [State]: you have edited the value as text, but not set the option. | 340 [State]: EDITED, shown value does not take effect until you set or @r{@dots{}} |
341 save it. | |
428 @end smallexample | 342 @end smallexample |
429 | 343 |
430 @cindex setting option value | 344 @cindex settings, how to set |
431 Editing the value does not actually set the option variable. To do | 345 Editing the value does not actually set the variable. To do that, |
432 that, you must @dfn{set} the option. To do this, invoke the word | 346 you must @dfn{set} the variable. To do this, invoke the |
433 @samp{[State]} and choose @samp{Set for Current Session}. | 347 @samp{[State]} button and choose @samp{Set for Current Session}. |
434 | 348 |
435 The state of the option changes visibly when you set it: | 349 The state of the variable changes visibly when you set it: |
436 | 350 |
437 @smallexample | 351 @smallexample |
438 [State]: you have set this option, but not saved it for future sessions. | 352 [State]: SET for current session only. |
439 @end smallexample | 353 @end smallexample |
440 | 354 |
441 You don't have to worry about specifying a value that is not valid; | 355 You don't have to worry about specifying a value that is not valid; |
442 setting the option checks for validity and will not really install an | 356 the @samp{Set for Current Session} operation checks for validity and |
443 unacceptable value. | 357 will not install an unacceptable value. |
444 | 358 |
445 @kindex M-TAB @r{(customization buffer)} | 359 @kindex M-TAB @r{(customization buffer)} |
446 @findex widget-complete | 360 @findex widget-complete |
447 While editing a value or field that is a file name, directory name, | 361 While editing a field that is a file name, directory name, |
448 command name, or anything else for which completion is defined, you can | 362 command name, or anything else for which completion is defined, you |
449 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. | 363 can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. |
450 | 364 (@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) |
451 Some options have a small fixed set of possible legitimate values. | 365 |
452 These options don't let you edit the value textually. Instead, an | 366 Some variables have a small fixed set of possible legitimate values. |
453 active field @samp{[Value Menu]} appears before the value; invoke this | 367 These variables don't let you edit the value textually. Instead, a |
454 field to edit the value. For a boolean ``on or off'' value, the active | 368 @samp{[Value Menu]} button appears before the value; invoke this |
455 field says @samp{[Toggle]}, and it changes to the other value. | 369 button to change the value. For a boolean ``on or off'' value, the |
456 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes | 370 button says @samp{[Toggle]}, and it changes to the other value. |
457 take effect when you use the @samp{Set for Current Session} operation. | 371 @samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the |
458 | 372 changes take real effect when you use the @samp{Set for Current |
459 Some options have values with complex structure. For example, the | 373 Session} operation. |
374 | |
375 Some variables have values with complex structure. For example, the | |
460 value of @code{file-coding-system-alist} is an association list. Here | 376 value of @code{file-coding-system-alist} is an association list. Here |
461 is how it appears in the customization buffer: | 377 is how it appears in the customization buffer: |
462 | 378 |
463 @smallexample | 379 @smallexample |
464 File Coding System Alist: [Hide] | 380 File Coding System Alist: [Hide Value] |
465 [INS] [DEL] File regexp: \.elc\' | 381 [INS] [DEL] File regexp: \.elc\' |
466 Choice: [Value Menu] Encoding/decoding pair: | 382 Choice: [Value Menu] Encoding/decoding pair: |
467 Decoding: emacs-mule | 383 Decoding: emacs-mule |
468 Encoding: emacs-mule | 384 Encoding: emacs-mule |
469 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' | 385 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' |
477 [INS] [DEL] File regexp: | 393 [INS] [DEL] File regexp: |
478 Choice: [Value Menu] Encoding/decoding pair: | 394 Choice: [Value Menu] Encoding/decoding pair: |
479 Decoding: undecided | 395 Decoding: undecided |
480 Encoding: nil | 396 Encoding: nil |
481 [INS] | 397 [INS] |
482 [State]: this option is unchanged from its standard setting. | 398 [State]: STANDARD. |
483 Alist to decide a coding system to use for a file I/O operation. [Hide] | 399 Alist to decide a coding system to use for a file I/O @r{@dots{}} |
400 operation. [Hide Rest] | |
484 The format is ((PATTERN . VAL) ...), | 401 The format is ((PATTERN . VAL) ...), |
485 where PATTERN is a regular expression matching a file name, | 402 where PATTERN is a regular expression matching a file name, |
486 @r{[@dots{}more lines of documentation@dots{}]} | 403 @r{[@dots{}more lines of documentation@dots{}]} |
487 @end smallexample | 404 @end smallexample |
488 | 405 |
489 @noindent | 406 @noindent |
490 Each association in the list appears on four lines, with several | 407 Each association in the list appears on four lines, with several |
491 editable or ``active'' fields. You can edit the regexps and coding | 408 editable fields and/or buttons. You can edit the regexps and coding |
492 systems using ordinary editing commands. You can also invoke | 409 systems using ordinary editing commands. You can also invoke |
493 @samp{[Value Menu]} to switch to a kind of value---for instance, to | 410 @samp{[Value Menu]} to switch to a different kind of value---for |
494 specify a function instead of a pair of coding systems. | 411 instance, to specify a function instead of a pair of coding systems. |
495 | 412 |
496 To delete an association from the list, invoke the @samp{[DEL]} button | 413 To delete an association from the list, invoke the @samp{[DEL]} button |
497 for that item. To add an association, invoke @samp{[INS]} at the | 414 for that item. To add an association, invoke @samp{[INS]} at the |
498 position where you want to add it. There is an @samp{[INS]} button | 415 position where you want to add it. There is an @samp{[INS]} button |
499 between each pair of association, another at the beginning and another | 416 between each pair of association, another at the beginning and another |
502 | 419 |
503 @kindex TAB @r{(customization buffer)} | 420 @kindex TAB @r{(customization buffer)} |
504 @kindex S-TAB @r{(customization buffer)} | 421 @kindex S-TAB @r{(customization buffer)} |
505 @findex widget-forward | 422 @findex widget-forward |
506 @findex widget-backward | 423 @findex widget-backward |
507 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for | 424 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful |
508 moving through the customization buffer. @key{TAB} | 425 for moving through the customization buffer. @key{TAB} |
509 (@code{widget-forward}) moves forward to the next active or editable | 426 (@code{widget-forward}) moves forward to the next button or editable |
510 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the | 427 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to |
511 previous active or editable field. | 428 the previous button or editable field. |
512 | 429 |
513 Typing @key{RET} on an editable field also moves forward, just like | 430 Typing @key{RET} on an editable field also moves forward, just like |
514 @key{TAB}. We set it up this way because people often type @key{RET} | 431 @key{TAB}. We set it up this way because people often type @key{RET} |
515 when they are finished editing a field. To insert a newline within an | 432 when they are finished editing a field. To insert a newline within an |
516 editable field, use @kbd{C-o} or @kbd{C-q C-j}. | 433 editable field, use @kbd{C-o} or @kbd{C-q C-j}. |
517 | 434 |
518 @cindex saving option value | 435 @cindex saving a setting |
519 @cindex customized options, saving | 436 @cindex settings, how to save |
520 Setting the option changes its value in the current Emacs session; | 437 Setting the variable changes its value in the current Emacs session; |
521 @dfn{saving} the value changes it for future sessions as well. To | 438 @dfn{saving} the value changes it for future sessions as well. To |
522 save the option, invoke @samp{[State]} and select the @samp{Save for | 439 save the variable, invoke @samp{[State]} and select the @samp{Save for |
523 Future Sessions} operation. This works by writing code so as to set | 440 Future Sessions} operation. This works by writing code so as to set |
524 the option variable again each time you start Emacs (@pxref{Saving | 441 the variable again, each time you start Emacs (@pxref{Saving |
525 Customizations}). | 442 Customizations}). |
526 | 443 |
527 You can also restore the option to its standard value by invoking | 444 You can also restore the variable to its standard value by invoking |
528 @samp{[State]} and selecting the @samp{Erase Customization} operation. | 445 @samp{[State]} and selecting the @samp{Erase Customization} operation. |
529 There are actually three reset operations: | 446 There are actually four reset operations: |
530 | 447 |
531 @table @samp | 448 @table @samp |
532 @item Reset | 449 @item Undo Edits |
533 If you have made some modifications and not yet set the option, | 450 If you have made some modifications and not yet set the variable, |
534 this restores the text in the customization buffer to match | 451 this restores the text in the customization buffer to match |
535 the actual value. | 452 the actual value. |
536 | 453 |
537 @item Reset to Saved | 454 @item Reset to Saved |
538 This restores the value of the option to the last saved value, | 455 This restores the value of the variable to the last saved value, |
539 and updates the text accordingly. | 456 and updates the text accordingly. |
540 | 457 |
541 @item Erase Customization | 458 @item Erase Customization |
542 This sets the option to its standard value, and updates the text | 459 This sets the variable to its standard value, and updates the text |
543 accordingly. This also eliminates any saved value for the option, | 460 accordingly. This also eliminates any saved value for the variable, |
544 so that you will get the standard value in future Emacs sessions. | 461 so that you will get the standard value in future Emacs sessions. |
545 | 462 |
546 @item Use Backup Value | 463 @item Set to Backup Value |
547 This sets the option to a previous value that was set in the | 464 This sets the variable to a previous value that was set in the |
548 customization buffer in this session. If you customize a variable | 465 customization buffer in this session. If you customize a variable |
549 and then reset the variable, which discards the customized value, | 466 and then reset it, which discards the customized value, |
550 you can get the customized value back again with this operation. | 467 you can get the customized value back again with this operation. |
551 @end table | 468 @end table |
552 | 469 |
553 @cindex comments on customized options | 470 @cindex comments on customized options |
554 Sometimes it is useful to record a comment about a specific | 471 Sometimes it is useful to record a comment about a specific |
555 customization. Use the @samp{Add Comment} item from the | 472 customization. Use the @samp{Add Comment} item from the |
556 @samp{[State]} menu to create a field for entering the comment. The | 473 @samp{[State]} menu to create a field for entering the comment. The |
557 comment you enter will be saved, and displayed again if you again view | 474 comment you enter will be saved, and displayed again if you again view |
558 the same option in a customization buffer, even in another session. | 475 the same variable in a customization buffer, even in another session. |
559 | 476 |
560 The state of a group indicates whether anything in that group has been | 477 The state of a group indicates whether anything in that group has been |
561 edited, set or saved. You can select @samp{Set for Current Session}, | 478 edited, set or saved. |
562 @samp{Save for Future Sessions} and the various kinds of @samp{Reset} | 479 |
563 operation for the group; these operations on the group apply to all | 480 Near the top of the customization buffer there are two lines of buttons: |
564 options in the group and its subgroups. | |
565 | |
566 Near the top of the customization buffer there are two lines | |
567 containing several active fields: | |
568 | 481 |
569 @smallexample | 482 @smallexample |
570 [Set for Current Session] [Save for Future Sessions] | 483 [Set for Current Session] [Save for Future Sessions] |
571 [Reset] [Reset to Saved] [Erase Customization] [Finish] | 484 [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] |
572 @end smallexample | 485 @end smallexample |
573 | 486 |
574 @vindex custom-buffer-done-function | 487 @vindex custom-buffer-done-function |
575 @noindent | 488 @noindent |
576 Invoking @samp{[Finish]} either buries or kills this customization | 489 Invoking @samp{[Finish]} either buries or kills this customization |
577 buffer according to the setting of the option | 490 buffer according to the setting of the option |
578 @code{custom-buffer-done-function}; the default is to bury the buffer. | 491 @code{custom-buffer-done-kill}; the default is to bury the buffer. |
579 Each of the other fields performs an operation---set, save or | 492 Each of the other buttons performs an operation---set, save or |
580 reset---on each of the items in the buffer that could meaningfully be | 493 reset---on each of the settings in the buffer that could meaningfully |
581 set, saved or reset. | 494 be set, saved or reset. They do not operate on settings whose values |
495 are hidden, nor on subgroups not visible in the buffer. | |
582 | 496 |
583 @node Saving Customizations | 497 @node Saving Customizations |
584 @subsubsection Saving Customizations | 498 @subsection Saving Customizations |
585 | 499 |
586 @vindex custom-file | 500 @vindex custom-file |
587 The customization buffer normally saves customizations in | 501 The customization buffer normally saves customizations in |
588 @file{~/.emacs}. If you wish, you can save customizations in another | 502 @file{~/.emacs}. If you wish, you can save customizations in another |
589 file instead. To make this work, your @file{~/.emacs} should set | 503 file instead. To make this work, your @file{~/.emacs} should set |
590 @code{custom-file} to the name of that file. Emacs loads the file | 504 @code{custom-file} to the name of that file. Then you should load the |
591 right after your @file{.emacs} if you did not load it already. For | 505 file by calling @code{load}. For example: |
592 example: | 506 |
593 | 507 @example |
594 @example | 508 (setq custom-file "~/.emacs-custom.el") |
595 (setq custom-file "~/.emacs-custom") | 509 (load custom-file) |
596 @end example | 510 @end example |
597 | 511 |
598 The variable @code{custom-file} is useful if you want to have | 512 You can also use @code{custom-file} to specify different |
599 different customizations for different Emacs versions: | 513 customization files for different Emacs versions, like this: |
600 | 514 |
601 @example | 515 @example |
602 (if (< emacs-major-version 21) | 516 (cond ((< emacs-major-version 21) |
603 ;; @r{Emacs 20 customization.} | 517 ;; @r{Emacs 20 customization.} |
604 (setq custom-file "~/.custom-20.el") | 518 (setq custom-file "~/.custom-20.el")) |
605 ;; @r{Emacs 21 customization.} | 519 ((and (= emacs-major-version 21) (< emacs-minor-version 4)) |
606 (setq custom-file "~/.custom-21.el")) | 520 ;; @r{Emacs 21 customization, before version 21.4.} |
521 (setq custom-file "~/.custom-21.el")) | |
522 ((< emacs-major-version 22) | |
523 ;; @r{Emacs version 21.4 or later.} | |
524 (setq custom-file "~/.custom-21.4.el")) | |
525 (t | |
526 ;; @r{Emacs version 22.1 or later.} | |
527 (setq custom-file "~/.custom-22.el"))) | |
528 | |
529 (load custom-file) | |
607 @end example | 530 @end example |
608 | 531 |
609 If Emacs was invoked with the @option{-q} or @option{--no-init-file} | 532 If Emacs was invoked with the @option{-q} or @option{--no-init-file} |
610 options (@pxref{Initial Options}), it will not let you save your | 533 options (@pxref{Initial Options}), it will not let you save your |
611 customizations in your @file{~/.emacs} init file. This is because | 534 customizations in your @file{~/.emacs} init file. This is because |
612 saving customizations from such a session would wipe out all the other | 535 saving customizations from such a session would wipe out all the other |
613 customizations you might have on your init file. | 536 customizations you might have on your init file. |
614 | 537 |
615 @node Face Customization | 538 @node Face Customization |
616 @subsubsection Customizing Faces | 539 @subsection Customizing Faces |
617 @cindex customizing faces | 540 @cindex customizing faces |
618 @cindex bold font | 541 @cindex bold font |
619 @cindex italic font | 542 @cindex italic font |
620 @cindex fonts and faces | 543 @cindex fonts and faces |
621 | 544 |
622 In addition to user options, some customization groups also include | 545 In addition to variables, some customization groups also include |
623 faces. When you show the contents of a group, both the user options and | 546 faces. When you show the contents of a group, both the variables and |
624 the faces in the group appear in the customization buffer. Here is an | 547 the faces in the group appear in the customization buffer. Here is an |
625 example of how a face looks: | 548 example of how a face looks: |
626 | 549 |
627 @smallexample | 550 @smallexample |
628 Custom Changed Face:(sample) [Hide] | 551 Custom Changed Face:(sample) [Hide Face] |
629 [State]: this face is unchanged from its standard setting. | 552 [State]: STANDARD. |
630 Face used when the customize item has been changed. | 553 Face used when the customize item has been changed. |
631 Parent groups: => Custom Magic Faces | 554 Parent groups: [Custom Magic Faces] |
632 Attributes: [ ] Font Family: * | 555 Attributes: [ ] Font Family: * |
633 [ ] Width: * | 556 [ ] Width: * |
634 [ ] Height: * | 557 [ ] Height: * |
635 [ ] Weight: * | 558 [ ] Weight: * |
636 [ ] Slant: * | 559 [ ] Slant: * |
643 [X] Background: blue (sample) | 566 [X] Background: blue (sample) |
644 [ ] Stipple: * | 567 [ ] Stipple: * |
645 [ ] Inherit: * | 568 [ ] Inherit: * |
646 @end smallexample | 569 @end smallexample |
647 | 570 |
648 Each face attribute has its own line. The @samp{[@var{x}]} field | 571 Each face attribute has its own line. The @samp{[@var{x}]} button |
649 before the attribute name indicates whether the attribute is | 572 before the attribute name indicates whether the attribute is |
650 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the | 573 @dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} |
651 attribute by invoking that field. When the attribute is enabled, you | 574 means that it's disabled. You can enable or disable the attribute by |
652 can change the attribute value in the usual ways. | 575 clicking that button. When the attribute is enabled, you can change |
653 | 576 the attribute value in the usual ways. |
654 On a black-and-white display, the colors you can use for the | 577 |
655 background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, | 578 For the colors, you can specify a color name (use @kbd{M-x |
656 and @samp{gray3}. Emacs supports these shades of gray by using | 579 list-colors-display} for a list of them) or a hexadecimal color |
657 background stipple patterns instead of a color. | 580 specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. |
581 (@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is | |
582 green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a | |
583 black-and-white display, the colors you can use for the background are | |
584 @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and | |
585 @samp{gray3}. Emacs supports these shades of gray by using background | |
586 stipple patterns instead of a color. | |
658 | 587 |
659 Setting, saving and resetting a face work like the same operations for | 588 Setting, saving and resetting a face work like the same operations for |
660 options (@pxref{Changing an Option}). | 589 variables (@pxref{Changing a Variable}). |
661 | 590 |
662 A face can specify different appearances for different types of | 591 A face can specify different appearances for different types of |
663 display. For example, a face can make text red on a color display, but | 592 display. For example, a face can make text red on a color display, but |
664 use a bold font on a monochrome display. To specify multiple | 593 use a bold font on a monochrome display. To specify multiple |
665 appearances for a face, select @samp{Show all display specs} in the menu you | 594 appearances for a face, select @samp{For All Kinds of Displays} in the |
666 get from invoking @samp{[State]}. | 595 menu you get from invoking @samp{[State]}. |
667 | 596 |
668 @findex modify-face | 597 @findex modify-face |
669 Another more basic way to set the attributes of a specific face is | 598 Another more basic way to set the attributes of a specific face is |
670 with @kbd{M-x modify-face}. This command reads the name of a face, then | 599 with @kbd{M-x modify-face}. This command reads the name of a face, then |
671 reads the attributes one by one. For the color and stipple attributes, | 600 reads the attributes one by one. For the color and stipple attributes, |
672 the attribute's current value is the default---type just @key{RET} if | 601 the attribute's current value is the default---type just @key{RET} if |
673 you don't want to change that attribute. Type @samp{none} if you want | 602 you don't want to change that attribute. Type @samp{none} if you want |
674 to clear out the attribute. | 603 to clear out the attribute. |
675 | 604 |
676 @node Specific Customization | 605 @node Specific Customization |
677 @subsubsection Customizing Specific Items | 606 @subsection Customizing Specific Items |
678 | 607 |
679 Instead of finding the options you want to change by moving down | 608 Instead of finding the setting you want to change by navigating the |
680 through the structure of groups, you can specify the particular option, | 609 structure of groups, here are other ways to specify the settings that |
681 face or group that you want to customize. | 610 you want to customize. |
682 | 611 |
683 @table @kbd | 612 @table @kbd |
684 @item M-x customize-option @key{RET} @var{option} @key{RET} | 613 @item M-x customize-variable @key{RET} @var{variable} @key{RET} |
685 Set up a customization buffer with just one option, @var{option}. | 614 Set up a customization buffer with just one variable, @var{variable}. |
686 @item M-x customize-face @key{RET} @var{face} @key{RET} | 615 @item M-x customize-face @key{RET} @var{face} @key{RET} |
687 Set up a customization buffer with just one face, @var{face}. | 616 Set up a customization buffer with just one face, @var{face}. |
688 @item M-x customize-group @key{RET} @var{group} @key{RET} | 617 @item M-x customize-group @key{RET} @var{group} @key{RET} |
689 Set up a customization buffer with just one group, @var{group}. | 618 Set up a customization buffer with just one group, @var{group}. |
690 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET} | 619 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET} |
691 Set up a customization buffer with all the options, faces and groups | 620 Set up a customization buffer with all the settings and groups that |
692 that match @var{regexp}. | 621 match @var{regexp}. |
693 @item M-x customize-changed-options @key{RET} @var{version} @key{RET} | 622 @item M-x customize-changed-options @key{RET} @var{version} @key{RET} |
694 Set up a customization buffer with all the options, faces and groups | 623 Set up a customization buffer with all the settings and groups |
695 whose meaning has changed since Emacs version @var{version}. | 624 whose meaning has changed since Emacs version @var{version}. |
696 @item M-x customize-saved | 625 @item M-x customize-saved |
697 Set up a customization buffer containing all options and faces that you | 626 Set up a customization buffer containing all settings that you |
698 have saved with customization buffers. | 627 have saved with customization buffers. |
699 @item M-x customize-customized | 628 @item M-x customize-customized |
700 Set up a customization buffer containing all options and faces that you | 629 Set up a customization buffer containing all settings that you have |
701 have customized but not saved. | 630 customized but not saved. |
702 @end table | 631 @end table |
703 | 632 |
704 @findex customize-option | 633 @findex customize-variable |
705 If you want to alter a particular user option variable with the | 634 If you want to alter a particular variable with the customization |
706 customization buffer, and you know its name, you can use the command | 635 buffer, and you know its name, you can use the command @kbd{M-x |
707 @kbd{M-x customize-option} and specify the option name. This sets up | 636 customize-variable} and specify the variable name. This sets up the |
708 the customization buffer with just one option---the one that you asked | 637 customization buffer with just one variable---the one that you asked |
709 for. Editing, setting and saving the value work as described above, but | 638 for. Editing, setting and saving the value work as described above, |
710 only for the specified option. | 639 but only for the specified variable. Minibuffer completion is handy |
640 if you only know part of the name. However, this command can only see | |
641 options that have been loaded in the current Emacs session. | |
711 | 642 |
712 @findex customize-face | 643 @findex customize-face |
713 Likewise, you can modify a specific face, chosen by name, using | 644 Likewise, you can modify a specific face, chosen by name, using |
714 @kbd{M-x customize-face}. By default it operates on the face used | 645 @kbd{M-x customize-face}. By default it operates on the face used |
715 on the character after point. | 646 on the character after point. |
716 | 647 |
717 @findex customize-group | 648 @findex customize-group |
718 You can also set up the customization buffer with a specific group, | 649 You can also set up the customization buffer with a specific group, |
719 using @kbd{M-x customize-group}. The immediate contents of the chosen | 650 using @kbd{M-x customize-group}. The immediate contents of the chosen |
720 group, including option variables, faces, and other groups, all appear | 651 group, including variables, faces, and other groups, all appear |
721 as well. However, these subgroups' own contents start out hidden. You | 652 as well (even if not already loaded). However, the subgroups' own |
722 can show their contents in the usual way, by invoking @samp{[Show]}. | 653 contents are not included. |
723 | 654 |
724 @findex customize-apropos | 655 @findex customize-apropos |
725 To control more precisely what to customize, you can use @kbd{M-x | 656 To control more precisely what to customize, you can use @kbd{M-x |
726 customize-apropos}. You specify a regular expression as argument; then | 657 customize-apropos}. You specify a regular expression as argument; |
727 all options, faces and groups whose names match this regular expression | 658 then all @emph{loaded} settings and groups whose names match this |
728 are set up in the customization buffer. If you specify an empty regular | 659 regular expression are set up in the customization buffer. If you |
729 expression, this includes @emph{all} groups, options and faces in the | 660 specify an empty regular expression, this includes @emph{all} loaded |
730 customization buffer (but that takes a long time). | 661 groups and settings---which takes a long time to set up. |
731 | 662 |
732 @findex customize-changed-options | 663 @findex customize-changed |
733 When you upgrade to a new Emacs version, you might want to customize | 664 When you upgrade to a new Emacs version, you might want to customize |
734 new options and options whose meanings or default values have changed. | 665 new settings and settings whose meanings or default values have |
735 To do this, use @kbd{M-x customize-changed-options} and specify a | 666 changed. To do this, use @kbd{M-x customize-changed} and |
736 previous Emacs version number using the minibuffer. It creates a | 667 specify a previous Emacs version number using the minibuffer. It |
737 customization buffer which shows all the options (and groups) whose | 668 creates a customization buffer which shows all the settings and groups |
738 definitions have been changed since the specified version. | 669 whose definitions have been changed since the specified version, loading |
670 them if necessary. | |
739 | 671 |
740 @findex customize-saved | 672 @findex customize-saved |
741 @findex customize-customized | 673 @findex customize-customized |
742 If you change option values and then decide the change was a mistake, | 674 If you change settings and then decide the change was a mistake, you |
743 you can use two special commands to revisit your previous changes. Use | 675 can use two special commands to revisit your previous changes. Use |
744 @kbd{M-x customize-saved} to look at the options and faces that you have | 676 @kbd{M-x customize-saved} to look at the settings that you have saved. |
745 saved. Use @kbd{M-x customize-customized} to look at the options and | 677 Use @kbd{M-x customize-customized} to look at the settings that you |
746 faces that you have set but not saved. | 678 have set but not saved. |
679 | |
680 @node Custom Themes | |
681 @subsection Customization Themes | |
682 @cindex custom themes | |
683 | |
684 @dfn{Custom themes} are collections of settings that can be enabled | |
685 or disabled as a unit. You can use Custom themes to switch quickly | |
686 and easily between various collections of settings, and to transfer | |
687 such collections from one computer to another. | |
688 | |
689 @findex customize-create-theme | |
690 To define a Custom theme, use @kbd{M-x customize-create-theme}, | |
691 which brings up a buffer named @samp{*New Custom Theme*}. At the top | |
692 of the buffer is an editable field where you can specify the name of | |
693 the theme. Click on the button labelled @samp{Insert Variable} to add | |
694 a variable to the theme, and click on @samp{Insert Face} to add a | |
695 face. You can edit these values in the @samp{*New Custom Theme*} | |
696 buffer like in an ordinary Customize buffer. To remove an option from | |
697 the theme, click on its @samp{State} button and select @samp{Delete}. | |
698 | |
699 @vindex custom-theme-directory | |
700 After adding the desired options, click on @samp{Save Theme} to save | |
701 the Custom theme. This writes the theme definition to a file | |
702 @file{@var{foo}-theme.el} (where @var{foo} is the theme name you | |
703 supplied), in the directory @file{~/.emacs.d/}. You can specify the | |
704 directory by setting @code{custom-theme-directory}. | |
705 | |
706 You can view and edit the settings of a previously-defined theme by | |
707 clicking on @samp{Visit Theme} and specifying the theme name. You can | |
708 also import the variables and faces that you have set using Customize | |
709 by visiting the ``special'' theme named @samp{user}. This theme, which | |
710 records all the options that you set in the ordinary customization | |
711 buffer, is always enabled, and always takes precedence over all other | |
712 enabled Custom themes. Additionally, the @samp{user} theme is | |
713 recorded in your @file{.emacs} file, rather than a | |
714 @file{user-theme.el} file. | |
715 | |
716 @vindex custom-enabled-themes | |
717 Once you have defined a Custom theme, you can use it by customizing | |
718 the variable @code{custom-enabled-themes}. This is a list of Custom | |
719 themes that are @dfn{enabled}, or put into effect. If you set | |
720 @code{custom-enabled-themes} using the Customize interface, the theme | |
721 definitions are automatically loaded from the theme files, if they | |
722 aren't already. If you save the value of @code{custom-enabled-themes} | |
723 for future Emacs sessions, those Custom themes will be enabled | |
724 whenever Emacs is started up. | |
725 | |
726 If two enabled themes specify different values for an option, the | |
727 theme occurring earlier in @code{custom-enabled-themes} takes effect. | |
728 | |
729 @findex load-theme | |
730 @findex enable-theme | |
731 @findex disable-theme | |
732 You can also enable a Custom theme with @kbd{M-x enable-theme}. | |
733 This prompts for a theme name in the minibuffer, loads the theme from | |
734 the theme file if necessary, and enables the theme. An enabled theme | |
735 can be @dfn{disabled} with the command @kbd{M-x disable-theme}; this | |
736 returns the options specified in the theme to their original values. | |
737 To re-enable the theme, call @kbd{M-x enable-theme} again. If a theme | |
738 file is changed during your Emacs session, you can reload it by | |
739 calling @kbd{M-x load-theme}. This also enables the theme. | |
740 | |
741 @node Variables | |
742 @section Variables | |
743 @cindex variable | |
744 @cindex option, user | |
745 @cindex user option | |
746 | |
747 A @dfn{variable} is a Lisp symbol which has a value. The symbol's | |
748 name is also called the name of the variable. A variable name can | |
749 contain any characters that can appear in a file, but conventionally | |
750 variable names consist of words separated by hyphens. A variable can | |
751 have a documentation string which describes what kind of value it should | |
752 have and how the value will be used. | |
753 | |
754 Emacs Lisp allows any variable (with a few exceptions) to have any | |
755 kind of value, but most variables that Emacs uses need a value of a | |
756 certain type. Often the value should always be a string, or should | |
757 always be a number. Sometimes we say that a certain feature is turned | |
758 on if a variable is ``non-@code{nil},'' meaning that if the variable's | |
759 value is @code{nil}, the feature is off, but the feature is on for | |
760 @emph{any} other value. The conventional value to use to turn on the | |
761 feature---since you have to pick one particular value when you set the | |
762 variable---is @code{t}. | |
763 | |
764 Emacs uses many Lisp variables for internal record keeping, but the | |
765 most interesting variables for a non-programmer user are those meant | |
766 for users to change---the @dfn{user options}. | |
767 | |
768 Each user option that you can set with the customization buffer is | |
769 in fact a Lisp variable. Emacs does not (usually) change the values | |
770 of these variables; instead, you set the values, and thereby alter and | |
771 control the behavior of certain Emacs commands. Use of the | |
772 customization buffer is explained above (@pxref{Easy Customization}); | |
773 here we describe other aspects of Emacs variables. | |
774 | |
775 @menu | |
776 * Examining:: Examining or setting one variable's value. | |
777 * Hooks:: Hook variables let you specify programs for parts | |
778 of Emacs to run on particular occasions. | |
779 * Locals:: Per-buffer values of variables. | |
780 * File Variables:: How files can specify variable values. | |
781 @end menu | |
782 | |
783 @node Examining | |
784 @subsection Examining and Setting Variables | |
785 @cindex setting variables | |
786 | |
787 @table @kbd | |
788 @item C-h v @var{var} @key{RET} | |
789 Display the value and documentation of variable @var{var} | |
790 (@code{describe-variable}). | |
791 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} | |
792 Change the value of variable @var{var} to @var{value}. | |
793 @end table | |
794 | |
795 To examine the value of a single variable, use @kbd{C-h v} | |
796 (@code{describe-variable}), which reads a variable name using the | |
797 minibuffer, with completion. It displays both the value and the | |
798 documentation of the variable. For example, | |
799 | |
800 @example | |
801 C-h v fill-column @key{RET} | |
802 @end example | |
803 | |
804 @noindent | |
805 displays something like this: | |
806 | |
807 @smallexample | |
808 fill-column's value is 70 | |
809 | |
810 Documentation: | |
811 *Column beyond which automatic line-wrapping should happen. | |
812 Automatically becomes buffer-local when set in any fashion. | |
813 @end smallexample | |
814 | |
815 @noindent | |
816 The star at the beginning of the documentation indicates that this | |
817 variable is a user option. @kbd{C-h v} is not restricted to user | |
818 options; it allows any variable name. | |
819 | |
820 @findex set-variable | |
821 The most convenient way to set a specific user option variable is | |
822 with @kbd{M-x set-variable}. This reads the variable name with the | |
823 minibuffer (with completion), and then reads a Lisp expression for the | |
824 new value using the minibuffer a second time (you can insert the old | |
825 value into the minibuffer for editing via @kbd{M-n}). For example, | |
826 | |
827 @example | |
828 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
829 @end example | |
830 | |
831 @noindent | |
832 sets @code{fill-column} to 75. | |
833 | |
834 @kbd{M-x set-variable} is limited to user option variables, but you can | |
835 set any variable with a Lisp expression, using the function @code{setq}. | |
836 Here is a @code{setq} expression to set @code{fill-column}: | |
837 | |
838 @example | |
839 (setq fill-column 75) | |
840 @end example | |
841 | |
842 To execute an expression like this one, go to the @samp{*scratch*} | |
843 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp | |
844 Interaction}. | |
845 | |
846 Setting variables, like all means of customizing Emacs except where | |
847 otherwise stated, affects only the current Emacs session. The only | |
848 way to alter the variable in future sessions is to put something in | |
849 the @file{~/.emacs} file to set it those sessions (@pxref{Init File}). | |
747 | 850 |
748 @node Hooks | 851 @node Hooks |
749 @subsection Hooks | 852 @subsection Hooks |
750 @cindex hook | 853 @cindex hook |
751 @cindex running a hook | 854 @cindex running a hook |
781 @code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because | 884 @code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because |
782 as soon as one hook function returns a non-@code{nil} value, the rest | 885 as soon as one hook function returns a non-@code{nil} value, the rest |
783 are not called at all. The documentation of each abnormal hook variable | 886 are not called at all. The documentation of each abnormal hook variable |
784 explains in detail what is peculiar about it. | 887 explains in detail what is peculiar about it. |
785 | 888 |
786 The recommended way to add a hook function to a hook (either normal or | 889 You can set a hook variable with @code{setq} like any other Lisp |
787 abnormal) is by calling @code{add-hook}. You can use any valid Lisp | 890 variable, but the recommended way to add a hook function to a hook |
788 function as the hook function, provided it can handle the proper number | 891 (either normal or abnormal) is by calling @code{add-hook}. You can |
789 of arguments (zero arguments, in the case of a normal hook). Of course, | 892 specify any valid Lisp function as the hook function, provided it can |
790 not every Lisp function is @emph{useful} in any particular hook. | 893 handle the proper number of arguments (zero arguments, in the case of |
894 a normal hook). Of course, not every Lisp function is @emph{useful} | |
895 in any particular hook. | |
791 | 896 |
792 For example, here's how to set up a hook to turn on Auto Fill mode | 897 For example, here's how to set up a hook to turn on Auto Fill mode |
793 when entering Text mode and other modes based on Text mode: | 898 when entering Text mode and other modes based on Text mode: |
794 | 899 |
795 @example | 900 @example |
826 It is best to design your hook functions so that the order in which | 931 It is best to design your hook functions so that the order in which |
827 they are executed does not matter. Any dependence on the order is | 932 they are executed does not matter. Any dependence on the order is |
828 ``asking for trouble.'' However, the order is predictable: the most | 933 ``asking for trouble.'' However, the order is predictable: the most |
829 recently added hook functions are executed first. | 934 recently added hook functions are executed first. |
830 | 935 |
936 If you play with adding various different versions of a hook | |
937 function by calling @code{add-hook} over and over, remember that all | |
938 the versions you added will remain in the hook variable together. You | |
939 can clear out individual functions with @code{remove-hook}, or do | |
940 @code{(setq @var{hook-variable} nil)} to remove everything. | |
941 | |
831 @node Locals | 942 @node Locals |
832 @subsection Local Variables | 943 @subsection Local Variables |
833 | 944 |
834 @table @kbd | 945 @table @kbd |
835 @item M-x make-local-variable @key{RET} @var{var} @key{RET} | 946 @item M-x make-local-variable @key{RET} @var{var} @key{RET} |
950 @end smallexample | 1061 @end smallexample |
951 | 1062 |
952 You can also specify the coding system for a file in this way: just | 1063 You can also specify the coding system for a file in this way: just |
953 specify a value for the ``variable'' named @code{coding}. The ``value'' | 1064 specify a value for the ``variable'' named @code{coding}. The ``value'' |
954 must be a coding system name that Emacs recognizes. @xref{Coding | 1065 must be a coding system name that Emacs recognizes. @xref{Coding |
955 Systems}. | 1066 Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a |
1067 particular Lisp file. @xref{Enabling Multibyte}. | |
956 | 1068 |
957 The @code{eval} pseudo-variable, described below, can be specified in | 1069 The @code{eval} pseudo-variable, described below, can be specified in |
958 the first line as well. | 1070 the first line as well. |
959 | 1071 |
960 @cindex shell scripts, and local file variables | 1072 @cindex shell scripts, and local file variables |
994 The usual reason for using a prefix and/or suffix is to embed the | 1106 The usual reason for using a prefix and/or suffix is to embed the |
995 local variables list in a comment, so it won't confuse other programs | 1107 local variables list in a comment, so it won't confuse other programs |
996 that the file is intended as input for. The example above is for a | 1108 that the file is intended as input for. The example above is for a |
997 language where comment lines start with @samp{;;; } and end with | 1109 language where comment lines start with @samp{;;; } and end with |
998 @samp{***}; the local values for @code{comment-start} and | 1110 @samp{***}; the local values for @code{comment-start} and |
999 @code{comment-end} customize the rest of Emacs for this unusual syntax. | 1111 @code{comment-end} customize the rest of Emacs for this unusual |
1000 Don't use a prefix (or a suffix) if you don't need one. | 1112 syntax. Don't use a prefix (or a suffix) if you don't need one. |
1001 | 1113 |
1002 Two ``variable names'' have special meanings in a local variables | 1114 If you write a multi-line string value, you should put the prefix |
1003 list: a value for the variable @code{mode} really sets the major mode, | 1115 and suffix on each line, even lines that start or end within the |
1004 and a value for the variable @code{eval} is simply evaluated as an | 1116 string. They will be stripped off for processing the list. If you |
1005 expression and the value is ignored. @code{mode} and @code{eval} are | 1117 want to split a long string across multiple lines of the file, you can |
1006 not real variables; setting variables named @code{mode} and @code{eval} | 1118 use backslash-newline, which is ignored in Lisp string constants. |
1007 in any other context has no special meaning. @emph{If @code{mode} is | 1119 Here's an example of doing this: |
1008 used to set a major mode, it should be the first ``variable'' in the | 1120 |
1009 list.} Otherwise, the entries that precede it in the list of the local | 1121 @example |
1010 variables are likely to be ignored, since most modes kill all local | 1122 # Local Variables: |
1011 variables as part of their initialization. | 1123 # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ |
1012 | 1124 # -Dmumble=blaah" |
1013 You can use the @code{mode} ``variable'' to set minor modes as well as | 1125 # End: |
1014 major modes; in fact, you can use it more than once, first to set the | 1126 @end example |
1015 major mode and then to set minor modes which are specific to particular | 1127 |
1016 buffers. But most minor modes should not be specified in the file in | 1128 Some ``variable names'' have special meanings in a local variables |
1017 any fashion, because they represent user preferences. | 1129 list. Specifying the ``variable'' @code{mode} really sets the major |
1130 mode, while any value specified for the ``variable'' @code{eval} is | |
1131 simply evaluated as an expression (its value is ignored). A value for | |
1132 @code{coding} specifies the coding system for character code | |
1133 conversion of this file, and a value of @code{t} for @code{unibyte} | |
1134 says to visit the file in a unibyte buffer. These four ``variables'' | |
1135 are not really variables; setting them in any other context has no | |
1136 special meaning. | |
1137 | |
1138 @emph{If @code{mode} is used to set a major mode, it should be the | |
1139 first ``variable'' in the list.} Otherwise, the entries that precede | |
1140 it will usually be ignored, since most modes kill all local variables | |
1141 as part of their initialization. | |
1142 | |
1143 You can use the @code{mode} ``variable'' to set minor modes as well | |
1144 as the major modes; in fact, you can use it more than once, first to | |
1145 set the major mode and then to set minor modes which are specific to | |
1146 particular buffers. But most minor modes should not be specified in | |
1147 the file at all, regardless of how, because they represent user | |
1148 preferences. | |
1018 | 1149 |
1019 For example, you may be tempted to try to turn on Auto Fill mode with | 1150 For example, you may be tempted to try to turn on Auto Fill mode with |
1020 a local variable list. That is a mistake. The choice of Auto Fill mode | 1151 a local variable list. That is a mistake. The choice of Auto Fill mode |
1021 or not is a matter of individual taste, not a matter of the contents of | 1152 or not is a matter of individual taste, not a matter of the contents of |
1022 particular files. If you want to use Auto Fill, set up major mode hooks | 1153 particular files. If you want to use Auto Fill, set up major mode hooks |
1047 | 1178 |
1048 @findex enable-local-eval | 1179 @findex enable-local-eval |
1049 The @code{eval} ``variable,'' and certain actual variables, create a | 1180 The @code{eval} ``variable,'' and certain actual variables, create a |
1050 special risk; when you visit someone else's file, local variable | 1181 special risk; when you visit someone else's file, local variable |
1051 specifications for these could affect your Emacs in arbitrary ways. | 1182 specifications for these could affect your Emacs in arbitrary ways. |
1052 Therefore, the option @code{enable-local-eval} controls whether Emacs | 1183 Therefore, the variable @code{enable-local-eval} controls whether Emacs |
1053 processes @code{eval} variables, as well variables with names that end | 1184 processes @code{eval} variables, as well variables with names that end |
1054 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions}, | 1185 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions}, |
1055 and certain other variables. The three possibilities for the option's | 1186 and certain other variables. The three possibilities for the variable's |
1056 value are @code{t}, @code{nil}, and anything else, just as for | 1187 value are @code{t}, @code{nil}, and anything else, just as for |
1057 @code{enable-local-variables}. The default is @code{maybe}, which is | 1188 @code{enable-local-variables}. The default is @code{maybe}, which is |
1058 neither @code{t} nor @code{nil}, so normally Emacs does ask for | 1189 neither @code{t} nor @code{nil}, so normally Emacs does ask for |
1059 confirmation about file settings for these variables. | 1190 confirmation about file settings for these variables. |
1060 | 1191 |
1061 @node Keyboard Macros | 1192 @findex safe-local-eval-forms |
1062 @section Keyboard Macros | 1193 The @code{safe-local-eval-forms} is a customizable list of eval |
1063 | 1194 forms which are safe to eval, so Emacs should not ask for |
1064 @cindex defining keyboard macros | 1195 confirmation to evaluate these forms, even if |
1065 @cindex keyboard macro | 1196 @code{enable-local-variables} says to ask for confirmation in general. |
1066 A @dfn{keyboard macro} is a command defined by the user to stand for | |
1067 another sequence of keys. For example, if you discover that you are | |
1068 about to type @kbd{C-n C-d} forty times, you can speed your work by | |
1069 defining a keyboard macro to do @kbd{C-n C-d} and calling it with a | |
1070 repeat count of forty. | |
1071 | |
1072 @table @kbd | |
1073 @item C-x ( | |
1074 Start defining a keyboard macro (@code{start-kbd-macro}). | |
1075 @item C-x ) | |
1076 End the definition of a keyboard macro (@code{end-kbd-macro}). | |
1077 @item C-x e | |
1078 Execute the most recent keyboard macro (@code{call-last-kbd-macro}). | |
1079 @item C-u C-x ( | |
1080 Re-execute last keyboard macro, then add more keys to its definition. | |
1081 @item C-x q | |
1082 When this point is reached during macro execution, ask for confirmation | |
1083 (@code{kbd-macro-query}). | |
1084 @item M-x name-last-kbd-macro | |
1085 Give a command name (for the duration of the session) to the most | |
1086 recently defined keyboard macro. | |
1087 @item M-x insert-kbd-macro | |
1088 Insert in the buffer a keyboard macro's definition, as Lisp code. | |
1089 @item C-x C-k | |
1090 Edit a previously defined keyboard macro (@code{edit-kbd-macro}). | |
1091 @item M-x apply-macro-to-region-lines | |
1092 Run the last keyboard macro on each complete line in the region. | |
1093 @end table | |
1094 | |
1095 Keyboard macros differ from ordinary Emacs commands in that they are | |
1096 written in the Emacs command language rather than in Lisp. This makes it | |
1097 easier for the novice to write them, and makes them more convenient as | |
1098 temporary hacks. However, the Emacs command language is not powerful | |
1099 enough as a programming language to be useful for writing anything | |
1100 intelligent or general. For such things, Lisp must be used. | |
1101 | |
1102 You define a keyboard macro while executing the commands which are the | |
1103 definition. Put differently, as you define a keyboard macro, the | |
1104 definition is being executed for the first time. This way, you can see | |
1105 what the effects of your commands are, so that you don't have to figure | |
1106 them out in your head. When you are finished, the keyboard macro is | |
1107 defined and also has been, in effect, executed once. You can then do the | |
1108 whole thing over again by invoking the macro. | |
1109 | |
1110 @menu | |
1111 * Basic Kbd Macro:: Defining and running keyboard macros. | |
1112 * Save Kbd Macro:: Giving keyboard macros names; saving them in files. | |
1113 * Kbd Macro Query:: Making keyboard macros do different things each time. | |
1114 @end menu | |
1115 | |
1116 @node Basic Kbd Macro | |
1117 @subsection Basic Use | |
1118 | |
1119 @kindex C-x ( | |
1120 @kindex C-x ) | |
1121 @kindex C-x e | |
1122 @findex start-kbd-macro | |
1123 @findex end-kbd-macro | |
1124 @findex call-last-kbd-macro | |
1125 To start defining a keyboard macro, type the @kbd{C-x (} command | |
1126 (@code{start-kbd-macro}). From then on, your keys continue to be | |
1127 executed, but also become part of the definition of the macro. @samp{Def} | |
1128 appears in the mode line to remind you of what is going on. When you are | |
1129 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the | |
1130 definition (without becoming part of it!). For example, | |
1131 | |
1132 @example | |
1133 C-x ( M-f foo C-x ) | |
1134 @end example | |
1135 | |
1136 @noindent | |
1137 defines a macro to move forward a word and then insert @samp{foo}. | |
1138 | |
1139 The macro thus defined can be invoked again with the @kbd{C-x e} | |
1140 command (@code{call-last-kbd-macro}), which may be given a repeat count | |
1141 as a numeric argument to execute the macro many times. @kbd{C-x )} can | |
1142 also be given a repeat count as an argument, in which case it repeats | |
1143 the macro that many times right after defining it, but defining the | |
1144 macro counts as the first repetition (since it is executed as you define | |
1145 it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro | |
1146 immediately 3 additional times. An argument of zero to @kbd{C-x e} or | |
1147 @kbd{C-x )} means repeat the macro indefinitely (until it gets an error | |
1148 or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}). | |
1149 | |
1150 If you wish to repeat an operation at regularly spaced places in the | |
1151 text, define a macro and include as part of the macro the commands to move | |
1152 to the next place you want to use it. For example, if you want to change | |
1153 each line, you should position point at the start of a line, and define a | |
1154 macro to change that line and leave point at the start of the next line. | |
1155 Then repeating the macro will operate on successive lines. | |
1156 | |
1157 When a command reads an argument with the minibuffer, your | |
1158 minibuffer input becomes part of the macro along with the command. So | |
1159 when you replay the macro, the command gets the same argument as | |
1160 when you entered the macro. For example, | |
1161 | |
1162 @example | |
1163 C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x ) | |
1164 @end example | |
1165 | |
1166 @noindent | |
1167 defines a macro that copies the current line into the buffer | |
1168 @samp{foo}, then returns to the original buffer. | |
1169 | |
1170 You can use function keys in a keyboard macro, just like keyboard | |
1171 keys. You can even use mouse events, but be careful about that: when | |
1172 the macro replays the mouse event, it uses the original mouse position | |
1173 of that event, the position that the mouse had while you were defining | |
1174 the macro. The effect of this may be hard to predict. (Using the | |
1175 current mouse position would be even less predictable.) | |
1176 | |
1177 One thing that doesn't always work well in a keyboard macro is the | |
1178 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command | |
1179 exits a recursive edit that started within the macro, it works as you'd | |
1180 expect. But if it exits a recursive edit that started before you | |
1181 invoked the keyboard macro, it also necessarily exits the keyboard macro | |
1182 as part of the process. | |
1183 | |
1184 After you have terminated the definition of a keyboard macro, you can add | |
1185 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent | |
1186 to plain @kbd{C-x (} followed by retyping the whole definition so far. As | |
1187 a consequence it re-executes the macro as previously defined. | |
1188 | |
1189 @findex edit-kbd-macro | |
1190 @kindex C-x C-k | |
1191 You can edit a keyboard macro already defined by typing @kbd{C-x C-k} | |
1192 (@code{edit-kbd-macro}). Follow that with the keyboard input that you | |
1193 would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or | |
1194 some other key sequence. This formats the macro definition in a buffer | |
1195 and enters a specialized major mode for editing it. Type @kbd{C-h m} | |
1196 once in that buffer to display details of how to edit the macro. When | |
1197 you are finished editing, type @kbd{C-c C-c}. | |
1198 | |
1199 @findex apply-macro-to-region-lines | |
1200 The command @kbd{M-x apply-macro-to-region-lines} repeats the last | |
1201 defined keyboard macro on each complete line within the current region. | |
1202 It does this line by line, by moving point to the beginning of the line | |
1203 and then executing the macro. | |
1204 | |
1205 @node Save Kbd Macro | |
1206 @subsection Naming and Saving Keyboard Macros | |
1207 | |
1208 @cindex saving keyboard macros | |
1209 @findex name-last-kbd-macro | |
1210 If you wish to save a keyboard macro for longer than until you define the | |
1211 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. | |
1212 This reads a name as an argument using the minibuffer and defines that name | |
1213 to execute the macro. The macro name is a Lisp symbol, and defining it in | |
1214 this way makes it a valid command name for calling with @kbd{M-x} or for | |
1215 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you | |
1216 specify a name that has a prior definition other than another keyboard | |
1217 macro, an error message is shown and nothing is changed. | |
1218 | |
1219 @findex insert-kbd-macro | |
1220 Once a macro has a command name, you can save its definition in a file. | |
1221 Then it can be used in another editing session. First, visit the file | |
1222 you want to save the definition in. Then use this command: | |
1223 | |
1224 @example | |
1225 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} | |
1226 @end example | |
1227 | |
1228 @noindent | |
1229 This inserts some Lisp code that, when executed later, will define the | |
1230 same macro with the same definition it has now. (You need not | |
1231 understand Lisp code to do this, because @code{insert-kbd-macro} writes | |
1232 the Lisp code for you.) Then save the file. You can load the file | |
1233 later with @code{load-file} (@pxref{Lisp Libraries}). If the file you | |
1234 save in is your init file @file{~/.emacs} (@pxref{Init File}) then the | |
1235 macro will be defined each time you run Emacs. | |
1236 | |
1237 If you give @code{insert-kbd-macro} a numeric argument, it makes | |
1238 additional Lisp code to record the keys (if any) that you have bound to the | |
1239 keyboard macro, so that the macro will be reassigned the same keys when you | |
1240 load the file. | |
1241 | |
1242 @node Kbd Macro Query | |
1243 @subsection Executing Macros with Variations | |
1244 | |
1245 @kindex C-x q | |
1246 @findex kbd-macro-query | |
1247 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect | |
1248 similar to that of @code{query-replace}, where the macro asks you each | |
1249 time around whether to make a change. While defining the macro, | |
1250 type @kbd{C-x q} at the point where you want the query to occur. During | |
1251 macro definition, the @kbd{C-x q} does nothing, but when you run the | |
1252 macro later, @kbd{C-x q} asks you interactively whether to continue. | |
1253 | |
1254 The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), | |
1255 @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. | |
1256 The answers are the same as in @code{query-replace}, though not all of | |
1257 the @code{query-replace} options are meaningful. | |
1258 | |
1259 These responses include @key{SPC} to continue, and @key{DEL} to skip | |
1260 the remainder of this repetition of the macro and start right away with | |
1261 the next repetition. @key{RET} means to skip the remainder of this | |
1262 repetition and cancel further repetitions. @kbd{C-l} redraws the screen | |
1263 and asks you again for a character to say what to do. | |
1264 | |
1265 @kbd{C-r} enters a recursive editing level, in which you can perform | |
1266 editing which is not part of the macro. When you exit the recursive | |
1267 edit using @kbd{C-M-c}, you are asked again how to continue with the | |
1268 keyboard macro. If you type a @key{SPC} at this time, the rest of the | |
1269 macro definition is executed. It is up to you to leave point and the | |
1270 text in a state such that the rest of the macro will do what you | |
1271 want.@refill | |
1272 | |
1273 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, | |
1274 performs a completely different function. It enters a recursive edit | |
1275 reading input from the keyboard, both when you type it during the | |
1276 definition of the macro, and when it is executed from the macro. During | |
1277 definition, the editing you do inside the recursive edit does not become | |
1278 part of the macro. During macro execution, the recursive edit gives you | |
1279 a chance to do some particularized editing on each repetition. | |
1280 @xref{Recursive Edit}. | |
1281 | |
1282 Another way to vary the behavior of a keyboard macro is to use a | |
1283 register as a counter, incrementing it on each repetition of the macro. | |
1284 @xref{RegNumbers}. | |
1285 | 1197 |
1286 @node Key Bindings | 1198 @node Key Bindings |
1287 @section Customizing Key Bindings | 1199 @section Customizing Key Bindings |
1288 @cindex key bindings | 1200 @cindex key bindings |
1289 | 1201 |
1302 * Minibuffer Maps:: The minibuffer uses its own local keymaps. | 1214 * Minibuffer Maps:: The minibuffer uses its own local keymaps. |
1303 * Rebinding:: How to redefine one key's meaning conveniently. | 1215 * Rebinding:: How to redefine one key's meaning conveniently. |
1304 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. | 1216 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. |
1305 * Function Keys:: Rebinding terminal function keys. | 1217 * Function Keys:: Rebinding terminal function keys. |
1306 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. | 1218 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. |
1307 * Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1. | 1219 * Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1. |
1308 * Mouse Buttons:: Rebinding mouse buttons in Emacs. | 1220 * Mouse Buttons:: Rebinding mouse buttons in Emacs. |
1309 * Disabling:: Disabling a command means confirmation is required | 1221 * Disabling:: Disabling a command means confirmation is required |
1310 before it can be executed. This is done to protect | 1222 before it can be executed. This is done to protect |
1311 beginners from surprises. | 1223 beginners from surprises. |
1312 @end menu | 1224 @end menu |
1351 @cindex function key | 1263 @cindex function key |
1352 Most modern keyboards have function keys as well as character keys. | 1264 Most modern keyboards have function keys as well as character keys. |
1353 Function keys send input events just as character keys do, and keymaps | 1265 Function keys send input events just as character keys do, and keymaps |
1354 can have bindings for them. | 1266 can have bindings for them. |
1355 | 1267 |
1356 On many terminals, typing a function key actually sends the computer a | 1268 On text terminals, typing a function key actually sends the computer a |
1357 sequence of characters; the precise details of the sequence depends on | 1269 sequence of characters; the precise details of the sequence depends on |
1358 which function key and on the model of terminal you are using. (Often | 1270 which function key and on the model of terminal you are using. (Often |
1359 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your | 1271 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your |
1360 terminal type properly, it recognizes the character sequences forming | 1272 terminal type properly, it recognizes the character sequences forming |
1361 function keys wherever they occur in a key sequence (not just at the | 1273 function keys wherever they occur in a key sequence (not just at the |
1400 The definition of a prefix key is usually the keymap to use for | 1312 The definition of a prefix key is usually the keymap to use for |
1401 looking up the following event. The definition can also be a Lisp | 1313 looking up the following event. The definition can also be a Lisp |
1402 symbol whose function definition is the following keymap; the effect is | 1314 symbol whose function definition is the following keymap; the effect is |
1403 the same, but it provides a command name for the prefix key that can be | 1315 the same, but it provides a command name for the prefix key that can be |
1404 used as a description of what the prefix key is for. Thus, the binding | 1316 used as a description of what the prefix key is for. Thus, the binding |
1405 of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function | 1317 of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function |
1406 definition is the keymap for @kbd{C-x} commands. The definitions of | 1318 definition is the keymap for @kbd{C-x} commands. The definitions of |
1407 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in | 1319 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in |
1408 the global map, so these prefix keys are always available. | 1320 the global map, so these prefix keys are always available. |
1409 | 1321 |
1410 Aside from ordinary prefix keys, there is a fictitious ``prefix key'' | 1322 Aside from ordinary prefix keys, there is a fictitious ``prefix key'' |
1513 @cindex minibuffer keymaps | 1425 @cindex minibuffer keymaps |
1514 @vindex minibuffer-local-map | 1426 @vindex minibuffer-local-map |
1515 @vindex minibuffer-local-ns-map | 1427 @vindex minibuffer-local-ns-map |
1516 @vindex minibuffer-local-completion-map | 1428 @vindex minibuffer-local-completion-map |
1517 @vindex minibuffer-local-must-match-map | 1429 @vindex minibuffer-local-must-match-map |
1430 @vindex minibuffer-local-filename-completion-map | |
1431 @vindex minibuffer-local-must-match-filename-map | |
1518 The minibuffer has its own set of local keymaps; they contain various | 1432 The minibuffer has its own set of local keymaps; they contain various |
1519 completion and exit commands. | 1433 completion and exit commands. |
1520 | 1434 |
1521 @itemize @bullet | 1435 @itemize @bullet |
1522 @item | 1436 @item |
1527 @item | 1441 @item |
1528 @code{minibuffer-local-completion-map} is for permissive completion. | 1442 @code{minibuffer-local-completion-map} is for permissive completion. |
1529 @item | 1443 @item |
1530 @code{minibuffer-local-must-match-map} is for strict completion and | 1444 @code{minibuffer-local-must-match-map} is for strict completion and |
1531 for cautious completion. | 1445 for cautious completion. |
1446 @item | |
1447 @code{minibuffer-local-filename-completion-map} and | |
1448 @code{minibuffer-local-must-match-filename-map} are like the two | |
1449 previous ones, but they are specifically for file name completion. | |
1450 They do not bind @key{SPC}. | |
1532 @end itemize | 1451 @end itemize |
1533 | 1452 |
1534 @node Rebinding | 1453 @node Rebinding |
1535 @subsection Changing Key Bindings Interactively | 1454 @subsection Changing Key Bindings Interactively |
1536 @cindex key rebinding, this session | 1455 @cindex key rebinding, this session |
1626 | 1545 |
1627 If you have a set of key bindings that you like to use all the time, | 1546 If you have a set of key bindings that you like to use all the time, |
1628 you can specify them in your @file{.emacs} file by using their Lisp | 1547 you can specify them in your @file{.emacs} file by using their Lisp |
1629 syntax. (@xref{Init File}.) | 1548 syntax. (@xref{Init File}.) |
1630 | 1549 |
1631 The simplest method for doing this works for ASCII characters and | 1550 The simplest method for doing this works for @acronym{ASCII} characters and |
1632 Meta-modified ASCII characters only. This method uses a string to | 1551 Meta-modified @acronym{ASCII} characters only. This method uses a string to |
1633 represent the key sequence you want to rebind. For example, here's how | 1552 represent the key sequence you want to rebind. For example, here's how |
1634 to bind @kbd{C-z} to @code{shell}: | 1553 to bind @kbd{C-z} to @code{shell}: |
1635 | 1554 |
1636 @example | 1555 @example |
1637 (global-set-key "\C-z" 'shell) | 1556 (global-set-key "\C-z" 'shell) |
1638 @end example | 1557 @end example |
1639 | 1558 |
1640 @noindent | 1559 @noindent |
1641 This example uses a string constant containing one character, @kbd{C-z}. | 1560 This example uses a string constant containing one character, |
1642 The single-quote before the command name, @code{shell}, marks it as a | 1561 @kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The |
1562 single-quote before the command name, @code{shell}, marks it as a | |
1643 constant symbol rather than a variable. If you omit the quote, Emacs | 1563 constant symbol rather than a variable. If you omit the quote, Emacs |
1644 would try to evaluate @code{shell} immediately as a variable. This | 1564 would try to evaluate @code{shell} immediately as a variable. This |
1645 probably causes an error; it certainly isn't what you want. | 1565 probably causes an error; it certainly isn't what you want. |
1646 | 1566 |
1647 Here is another example that binds a key sequence two characters long: | 1567 Here is another example that binds the key sequence @kbd{C-x M-l}: |
1648 | 1568 |
1649 @example | 1569 @example |
1650 (global-set-key "\C-xl" 'make-symbolic-link) | 1570 (global-set-key "\C-x\M-l" 'make-symbolic-link) |
1651 @end example | 1571 @end example |
1652 | 1572 |
1653 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the | 1573 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the |
1654 string, you can use the Emacs Lisp escape sequences, @samp{\t}, | 1574 string, you can use the Emacs Lisp escape sequences, @samp{\t}, |
1655 @samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds | 1575 @samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds |
1657 | 1577 |
1658 @example | 1578 @example |
1659 (global-set-key "\C-x\t" 'indent-rigidly) | 1579 (global-set-key "\C-x\t" 'indent-rigidly) |
1660 @end example | 1580 @end example |
1661 | 1581 |
1662 These examples show how to write some other special ASCII characters | 1582 These examples show how to write some other special @acronym{ASCII} characters |
1663 in strings for key bindings: | 1583 in strings for key bindings: |
1664 | 1584 |
1665 @example | 1585 @example |
1666 (global-set-key "\r" 'newline) ;; @key{RET} | 1586 (global-set-key "\r" 'newline) ;; @key{RET} |
1667 (global-set-key "\d" 'delete-backward-char) ;; @key{DEL} | 1587 (global-set-key "\d" 'delete-backward-char) ;; @key{DEL} |
1668 (global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC} | 1588 (global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC} |
1669 @end example | 1589 @end example |
1670 | 1590 |
1671 When the key sequence includes function keys or mouse button events, | 1591 When the key sequence includes function keys or mouse button events, |
1672 or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use | 1592 or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use |
1673 the more general method of rebinding, which uses a vector to specify the | 1593 the more general method of rebinding, which uses a vector to specify the |
1674 key sequence. | 1594 key sequence. |
1675 | 1595 |
1676 The way to write a vector in Emacs Lisp is with square brackets around | 1596 The way to write a vector in Emacs Lisp is with square brackets around |
1677 the vector elements. Use spaces to separate the elements. If an | 1597 the vector elements. Use spaces to separate the elements. If an |
1679 delimiters or punctuation are needed. If a vector element is a | 1599 delimiters or punctuation are needed. If a vector element is a |
1680 character, write it as a Lisp character constant: @samp{?} followed by | 1600 character, write it as a Lisp character constant: @samp{?} followed by |
1681 the character as it would appear in a string. | 1601 the character as it would appear in a string. |
1682 | 1602 |
1683 Here are examples of using vectors to rebind @kbd{C-=} (a control | 1603 Here are examples of using vectors to rebind @kbd{C-=} (a control |
1684 character not in ASCII), @kbd{C-M-=} (not in ASCII because @kbd{C-=} | 1604 character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=} |
1685 is not), @kbd{H-a} (a Hyper character; ASCII doesn't have Hyper at | 1605 is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at |
1686 all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a | 1606 all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a |
1687 keyboard-modified mouse button): | 1607 keyboard-modified mouse button): |
1688 | 1608 |
1689 @example | 1609 @example |
1690 (global-set-key [?\C-=] 'make-symbolic-link) | 1610 (global-set-key [?\C-=] 'make-symbolic-link) |
1693 (global-set-key [f7] 'make-symbolic-link) | 1613 (global-set-key [f7] 'make-symbolic-link) |
1694 (global-set-key [C-mouse-1] 'make-symbolic-link) | 1614 (global-set-key [C-mouse-1] 'make-symbolic-link) |
1695 @end example | 1615 @end example |
1696 | 1616 |
1697 You can use a vector for the simple cases too. Here's how to | 1617 You can use a vector for the simple cases too. Here's how to |
1698 rewrite the first three examples above, using vectors to bind | 1618 rewrite the first six examples above to use vectors: |
1699 @kbd{C-z}, @kbd{C-x l}, and @kbd{C-x @key{TAB}}: | |
1700 | 1619 |
1701 @example | 1620 @example |
1702 (global-set-key [?\C-z] 'shell) | 1621 (global-set-key [?\C-z] 'shell) |
1703 (global-set-key [?\C-x ?l] 'make-symbolic-link) | 1622 (global-set-key [?\C-x ?l] 'make-symbolic-link) |
1704 (global-set-key [?\C-x ?\t] 'indent-rigidly) | 1623 (global-set-key [?\C-x ?\t] 'indent-rigidly) |
1707 (global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command) | 1626 (global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command) |
1708 @end example | 1627 @end example |
1709 | 1628 |
1710 @noindent | 1629 @noindent |
1711 As you see, you represent a multi-character key sequence with a vector | 1630 As you see, you represent a multi-character key sequence with a vector |
1712 by listing each of the characters within the square brackets that | 1631 by listing all of the characters in order within the square brackets that |
1713 delimit the vector. | 1632 delimit the vector. |
1633 | |
1634 Language and coding systems can cause problems with key bindings | |
1635 for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}. | |
1714 | 1636 |
1715 @node Function Keys | 1637 @node Function Keys |
1716 @subsection Rebinding Function Keys | 1638 @subsection Rebinding Function Keys |
1717 | 1639 |
1718 Key sequences can contain function keys as well as ordinary | 1640 Key sequences can contain function keys as well as ordinary |
1753 X) may use different names. To make certain what symbol is used for a | 1675 X) may use different names. To make certain what symbol is used for a |
1754 given function key on your terminal, type @kbd{C-h c} followed by that | 1676 given function key on your terminal, type @kbd{C-h c} followed by that |
1755 key. | 1677 key. |
1756 | 1678 |
1757 A key sequence which contains function key symbols (or anything but | 1679 A key sequence which contains function key symbols (or anything but |
1758 ASCII characters) must be a vector rather than a string. The vector | 1680 @acronym{ASCII} characters) must be a vector rather than a string. |
1759 syntax uses spaces between the elements, and square brackets around the | 1681 Thus, to bind function key @samp{f1} to the command @code{rmail}, |
1760 whole vector. Thus, to bind function key @samp{f1} to the command | 1682 write the following: |
1761 @code{rmail}, write the following: | |
1762 | 1683 |
1763 @example | 1684 @example |
1764 (global-set-key [f1] 'rmail) | 1685 (global-set-key [f1] 'rmail) |
1765 @end example | 1686 @end example |
1766 | 1687 |
1800 | 1721 |
1801 @example | 1722 @example |
1802 (global-set-key [H-M-right] 'forward-word) | 1723 (global-set-key [H-M-right] 'forward-word) |
1803 @end example | 1724 @end example |
1804 | 1725 |
1726 @cindex keypad | |
1727 Many keyboards have a ``numeric keypad'' on the right hand side. | |
1728 The numeric keys in the keypad double up as cursor motion keys, | |
1729 toggled by a key labeled @samp{Num Lock}. By default, Emacs | |
1730 translates these keys to the corresponding keys in the main keyboard. | |
1731 For example, when @samp{Num Lock} is on, the key labeled @samp{8} on | |
1732 the numeric keypad produces @code{kp-8}, which is translated to | |
1733 @kbd{8}; when @samp{Num Lock} is off, the same key produces | |
1734 @code{kp-up}, which is translated to @key{UP}. If you rebind a key | |
1735 such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. | |
1736 However, if you rebind a @samp{kp-} key directly, that won't affect | |
1737 its non-keypad equivalent. | |
1738 | |
1739 Emacs provides a convenient method for binding the numeric keypad | |
1740 keys, using the variables @code{keypad-setup}, | |
1741 @code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and | |
1742 @code{keypad-numlock-shifted-setup}. These can be found in the | |
1743 @samp{keyboard} customization group (@pxref{Easy Customization}). You | |
1744 can rebind the keys to perform other tasks, such as issuing numeric | |
1745 prefix arguments. | |
1746 | |
1805 @node Named ASCII Chars | 1747 @node Named ASCII Chars |
1806 @subsection Named ASCII Control Characters | 1748 @subsection Named @acronym{ASCII} Control Characters |
1807 | 1749 |
1808 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} | 1750 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} |
1809 started out as names for certain ASCII control characters, used so often | 1751 started out as names for certain @acronym{ASCII} control characters, |
1810 that they have special keys of their own. Later, users found it | 1752 used so often that they have special keys of their own. For instance, |
1753 @key{TAB} was another name for @kbd{C-i}. Later, users found it | |
1811 convenient to distinguish in Emacs between these keys and the ``same'' | 1754 convenient to distinguish in Emacs between these keys and the ``same'' |
1812 control characters typed with the @key{CTRL} key. | 1755 control characters typed with the @key{CTRL} key. Therefore, on most |
1813 | 1756 modern terminals, they are no longer the same, and @key{TAB} is |
1814 Emacs distinguishes these two kinds of input, when the keyboard | 1757 distinguishable from @kbd{C-i}. |
1815 reports these keys to Emacs. It treats the ``special'' keys as function | 1758 |
1816 keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed}, | 1759 Emacs can distinguish these two kinds of input if the keyboard does. |
1817 @code{escape}, and @code{delete}. These function keys translate | 1760 It treats the ``special'' keys as function keys named @code{tab}, |
1818 automatically into the corresponding ASCII characters @emph{if} they | 1761 @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and |
1819 have no bindings of their own. As a result, neither users nor Lisp | 1762 @code{delete}. These function keys translate automatically into the |
1820 programs need to pay attention to the distinction unless they care to. | 1763 corresponding @acronym{ASCII} characters @emph{if} they have no |
1764 bindings of their own. As a result, neither users nor Lisp programs | |
1765 need to pay attention to the distinction unless they care to. | |
1821 | 1766 |
1822 If you do not want to distinguish between (for example) @key{TAB} and | 1767 If you do not want to distinguish between (for example) @key{TAB} and |
1823 @kbd{C-i}, make just one binding, for the ASCII character @key{TAB} | 1768 @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} |
1824 (octal code 011). If you do want to distinguish, make one binding for | 1769 (octal code 011). If you do want to distinguish, make one binding for |
1825 this ASCII character, and another for the ``function key'' @code{tab}. | 1770 this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. |
1826 | 1771 |
1827 With an ordinary ASCII terminal, there is no way to distinguish | 1772 With an ordinary @acronym{ASCII} terminal, there is no way to distinguish |
1828 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), | 1773 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), |
1829 because the terminal sends the same character in both cases. | 1774 because the terminal sends the same character in both cases. |
1830 | 1775 |
1831 @node Non-ASCII Rebinding | 1776 @node Non-ASCII Rebinding |
1832 @subsection Non-ASCII Characters on the Keyboard | 1777 @subsection Non-@acronym{ASCII} Characters on the Keyboard |
1833 @cindex rebinding non-ASCII keys | 1778 @cindex rebinding non-@acronym{ASCII} keys |
1834 @cindex non-ASCII keys, binding | 1779 @cindex non-@acronym{ASCII} keys, binding |
1835 | 1780 |
1836 If your keyboard has keys that send non-ASCII characters, such as | 1781 If your keyboard has keys that send non-@acronym{ASCII} |
1837 accented letters, rebinding these keys is a bit tricky. There are two | 1782 characters, such as accented letters, rebinding these keys |
1838 solutions you can use. One is to specify a keyboard coding system, | 1783 must be done by using a vector like this@footnote{Note that |
1839 using @code{set-keyboard-coding-system} (@pxref{Specify Coding}). | 1784 you should avoid the string syntax for binding |
1840 Then you can bind these keys in the usual way@footnote{Note that you | 1785 non-@acronym{ASCII} characters, since they will be |
1841 should avoid the string syntax for binding 8-bit characters, since | 1786 interpreted as meta keys. @xref{Strings of Events,,,elisp, |
1842 they will be interpreted as meta keys. @xref{Strings of | 1787 The Emacs Lisp Reference Manual}.}: |
1843 Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this: | |
1844 | 1788 |
1845 @example | 1789 @example |
1846 (global-set-key [?@var{char}] 'some-function) | 1790 (global-set-key [?@var{char}] 'some-function) |
1847 @end example | 1791 @end example |
1848 | 1792 |
1849 @noindent | 1793 @noindent |
1850 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}. | 1794 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}. |
1851 | 1795 |
1852 If you don't specify the keyboard coding system, that approach won't | 1796 Since this puts a non-@acronym{ASCII} character in the @file{.emacs}, |
1853 work. Instead, you need to find out the actual code that the terminal | 1797 you should specify a coding system for that file that supports the |
1854 sends. The easiest way to do this in Emacs is to create an empty buffer | 1798 character in question. @xref{Init Syntax}. |
1855 with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x | 1799 |
1856 toggle-enable-multibyte-characters @key{RET}}, then type the key to | 1800 @strong{Warning:} if you change the keyboard encoding, or change |
1857 insert the character into this buffer. | 1801 between multibyte and unibyte mode, or anything that would alter which |
1858 | 1802 code @kbd{C-q} would insert for that character, you'll need to edit |
1859 Move point before the character, then type @kbd{C-x =}. This | 1803 the Lisp expression accordingly, to use the character code generated |
1860 displays a message in the minibuffer, showing the character code in | 1804 by @kbd{C-q} in the new mode. |
1861 three ways, octal, decimal and hexadecimal, all within a set of | |
1862 parentheses. Use the second of the three numbers, the decimal one, | |
1863 inside the vector to bind: | |
1864 | |
1865 @example | |
1866 (global-set-key [@var{decimal-code}] 'some-function) | |
1867 @end example | |
1868 | |
1869 If you bind 8-bit characters like this in your init file, you may find it | |
1870 convenient to specify that it is unibyte. @xref{Enabling Multibyte}. | |
1871 | 1805 |
1872 @node Mouse Buttons | 1806 @node Mouse Buttons |
1873 @subsection Rebinding Mouse Buttons | 1807 @subsection Rebinding Mouse Buttons |
1874 @cindex mouse button events | 1808 @cindex mouse button events |
1875 @cindex rebinding mouse buttons | 1809 @cindex rebinding mouse buttons |
1927 twice. | 1861 twice. |
1928 | 1862 |
1929 Emacs also supports triple-click events whose names start with | 1863 Emacs also supports triple-click events whose names start with |
1930 @samp{triple-}. Emacs does not distinguish quadruple clicks as event | 1864 @samp{triple-}. Emacs does not distinguish quadruple clicks as event |
1931 types; clicks beyond the third generate additional triple-click events. | 1865 types; clicks beyond the third generate additional triple-click events. |
1932 However, the full number of clicks is recorded in the event list, so you | 1866 However, the full number of clicks is recorded in the event list, so |
1933 can distinguish if you really want to. We don't recommend distinct | 1867 if you know Emacs Lisp you can distinguish if you really want to |
1934 meanings for more than three clicks, but sometimes it is useful for | 1868 (@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}). |
1935 subsequent clicks to cycle through the same set of three meanings, so | 1869 We don't recommend distinct meanings for more than three clicks, but |
1936 that four clicks are equivalent to one click, five are equivalent to | 1870 sometimes it is useful for subsequent clicks to cycle through the same |
1937 two, and six are equivalent to three. | 1871 set of three meanings, so that four clicks are equivalent to one |
1872 click, five are equivalent to two, and six are equivalent to three. | |
1938 | 1873 |
1939 Emacs also records multiple presses in drag and button-down events. | 1874 Emacs also records multiple presses in drag and button-down events. |
1940 For example, when you press a button twice, then move the mouse while | 1875 For example, when you press a button twice, then move the mouse while |
1941 holding the button, Emacs gets a @samp{double-drag-} event. And at the | 1876 holding the button, Emacs gets a @samp{double-drag-} event. And at the |
1942 moment when you press it down for the second time, Emacs gets a | 1877 moment when you press it down for the second time, Emacs gets a |
1950 @code{nil}, double clicks are not detected at all. If the value is | 1885 @code{nil}, double clicks are not detected at all. If the value is |
1951 @code{t}, then there is no time limit. The default is 500. | 1886 @code{t}, then there is no time limit. The default is 500. |
1952 | 1887 |
1953 @vindex double-click-fuzz | 1888 @vindex double-click-fuzz |
1954 The variable @code{double-click-fuzz} specifies how much the mouse | 1889 The variable @code{double-click-fuzz} specifies how much the mouse |
1955 can move between clicks still allow them to be grouped as a multiple | 1890 can move between clicks and still allow them to be grouped as a multiple |
1956 click. Its value is in units of pixels on windowed displays and in | 1891 click. Its value is in units of pixels on windowed displays and in |
1957 units of 1/8 of a character cell on text-mode terminals; the default is | 1892 units of 1/8 of a character cell on text-mode terminals; the default is |
1958 3. | 1893 3. |
1959 | 1894 |
1960 The symbols for mouse events also indicate the status of the modifier | 1895 The symbols for mouse events also indicate the status of the modifier |
1984 The mouse was in the vertical line separating side-by-side windows. (If | 1919 The mouse was in the vertical line separating side-by-side windows. (If |
1985 you use scroll bars, they appear in place of these vertical lines.) | 1920 you use scroll bars, they appear in place of these vertical lines.) |
1986 @item vertical-scroll-bar | 1921 @item vertical-scroll-bar |
1987 The mouse was in a vertical scroll bar. (This is the only kind of | 1922 The mouse was in a vertical scroll bar. (This is the only kind of |
1988 scroll bar Emacs currently supports.) | 1923 scroll bar Emacs currently supports.) |
1924 @item menu-bar | |
1925 The mouse was in the menu bar. | |
1926 @item header-line | |
1927 The mouse was in a header line. | |
1989 @ignore | 1928 @ignore |
1990 @item horizontal-scroll-bar | 1929 @item horizontal-scroll-bar |
1991 The mouse was in a horizontal scroll bar. Horizontal scroll bars do | 1930 The mouse was in a horizontal scroll bar. Horizontal scroll bars do |
1992 horizontal scrolling, and people don't use them often. | 1931 horizontal scrolling, and people don't use them often. |
1993 @end ignore | 1932 @end ignore |
2046 Whether a command is disabled is independent of what key is used to | 1985 Whether a command is disabled is independent of what key is used to |
2047 invoke it; disabling also applies if the command is invoked using | 1986 invoke it; disabling also applies if the command is invoked using |
2048 @kbd{M-x}. Disabling a command has no effect on calling it as a | 1987 @kbd{M-x}. Disabling a command has no effect on calling it as a |
2049 function from Lisp programs. | 1988 function from Lisp programs. |
2050 | 1989 |
2051 @node Keyboard Translations | |
2052 @section Keyboard Translations | |
2053 | |
2054 Some keyboards do not make it convenient to send all the special | |
2055 characters that Emacs uses. The most common problem case is the | |
2056 @key{DEL} character. Some keyboards provide no convenient way to type | |
2057 this very important character---usually because they were designed to | |
2058 expect the character @kbd{C-h} to be used for deletion. On these | |
2059 keyboards, if you press the key normally used for deletion, Emacs handles | |
2060 the @kbd{C-h} as a prefix character and offers you a list of help | |
2061 options, which is not what you want. | |
2062 | |
2063 @cindex keyboard translations | |
2064 @findex keyboard-translate | |
2065 You can work around this problem within Emacs by setting up keyboard | |
2066 translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into | |
2067 @kbd{C-h}, as follows: | |
2068 | |
2069 @example | |
2070 ;; @r{Translate @kbd{C-h} to @key{DEL}.} | |
2071 (keyboard-translate ?\C-h ?\C-?) | |
2072 | |
2073 ;; @r{Translate @key{DEL} to @kbd{C-h}.} | |
2074 (keyboard-translate ?\C-? ?\C-h) | |
2075 @end example | |
2076 | |
2077 Keyboard translations are not the same as key bindings in keymaps | |
2078 (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in | |
2079 different situations, but there is only one set of keyboard | |
2080 translations, and it applies to every character that Emacs reads from | |
2081 the terminal. Keyboard translations take place at the lowest level of | |
2082 input processing; the keys that are looked up in keymaps contain the | |
2083 characters that result from keyboard translation. | |
2084 | |
2085 On a window system, the keyboard key named @key{DELETE} is a function | |
2086 key and is distinct from the ASCII character named @key{DEL}. | |
2087 @xref{Named ASCII Chars}. Keyboard translations affect only ASCII | |
2088 character input, not function keys; thus, the above example used on a | |
2089 window system does not affect the @key{DELETE} key. However, the | |
2090 translation above isn't necessary on window systems, because Emacs can | |
2091 also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it | |
2092 normally treats @key{BACKSPACE} as @key{DEL}. | |
2093 | |
2094 For full information about how to use keyboard translations, see | |
2095 @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}. | |
2096 | |
2097 @node Syntax | 1990 @node Syntax |
2098 @section The Syntax Table | 1991 @section The Syntax Table |
2099 @cindex syntax table | 1992 @cindex syntax table |
2100 | 1993 |
2101 All the Emacs commands which parse words or balance parentheses are | 1994 All the Emacs commands which parse words or balance parentheses are |
2130 @cindex Emacs initialization file | 2023 @cindex Emacs initialization file |
2131 @cindex key rebinding, permanent | 2024 @cindex key rebinding, permanent |
2132 @cindex rebinding keys, permanently | 2025 @cindex rebinding keys, permanently |
2133 @cindex startup (init file) | 2026 @cindex startup (init file) |
2134 | 2027 |
2135 When Emacs is started, it normally loads a Lisp program from the file | 2028 When Emacs is started, it normally loads a Lisp program from the |
2136 @file{.emacs} or @file{.emacs.el} in your home directory. We call this | 2029 file @file{.emacs} or @file{.emacs.el} in your home directory. We |
2137 file your @dfn{init file} because it specifies how to initialize Emacs | 2030 call this file your @dfn{init file} because it specifies how to |
2138 for you. You can use the command line switch @samp{-q} to prevent | 2031 initialize Emacs for you. You can use the command line switch |
2139 loading your init file, and @samp{-u} (or @samp{--user}) to specify a | 2032 @samp{-q} to prevent loading your init file, and @samp{-u} (or |
2140 different user's init file (@pxref{Entering Emacs}). | 2033 @samp{--user}) to specify a different user's init file (@pxref{Initial |
2034 Options}). | |
2035 | |
2036 You can also use @file{~/.emacs.d/init.el} as the init file. Emacs | |
2037 tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}. | |
2141 | 2038 |
2142 @cindex @file{default.el}, the default init file | 2039 @cindex @file{default.el}, the default init file |
2143 There can also be a @dfn{default init file}, which is the library | 2040 There can also be a @dfn{default init file}, which is the library |
2144 named @file{default.el}, found via the standard search path for | 2041 named @file{default.el}, found via the standard search path for |
2145 libraries. The Emacs distribution contains no such library; your site | 2042 libraries. The Emacs distribution contains no such library; your site |
2153 @cindex @file{site-start.el}, the site startup file | 2050 @cindex @file{site-start.el}, the site startup file |
2154 Your site may also have a @dfn{site startup file}; this is named | 2051 Your site may also have a @dfn{site startup file}; this is named |
2155 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs | 2052 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs |
2156 finds this file via the standard search path for Lisp libraries. | 2053 finds this file via the standard search path for Lisp libraries. |
2157 Emacs loads this library before it loads your init file. To inhibit | 2054 Emacs loads this library before it loads your init file. To inhibit |
2158 loading of this library, use the option @samp{-no-site-file}. | 2055 loading of this library, use the option @samp{--no-site-file}. |
2159 @xref{Initial Options}. | 2056 @xref{Initial Options}. We recommend against using |
2057 @file{site-start.el} for changes that some users may not like. It is | |
2058 better to put them in @file{default.el}, so that users can more easily | |
2059 override them. | |
2160 | 2060 |
2161 You can place @file{default.el} and @file{site-start.el} in any of | 2061 You can place @file{default.el} and @file{site-start.el} in any of |
2162 the directories which Emacs searches for Lisp libraries. The variable | 2062 the directories which Emacs searches for Lisp libraries. The variable |
2163 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories. | 2063 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories. |
2164 Many sites put these files in the @file{site-lisp} subdirectory of the | 2064 Many sites put these files in the @file{site-lisp} subdirectory of the |
2191 expressions. Each of these consists of a function name followed by | 2091 expressions. Each of these consists of a function name followed by |
2192 arguments, all surrounded by parentheses. For example, @code{(setq | 2092 arguments, all surrounded by parentheses. For example, @code{(setq |
2193 fill-column 60)} calls the function @code{setq} to set the variable | 2093 fill-column 60)} calls the function @code{setq} to set the variable |
2194 @code{fill-column} (@pxref{Filling}) to 60. | 2094 @code{fill-column} (@pxref{Filling}) to 60. |
2195 | 2095 |
2196 The second argument to @code{setq} is an expression for the new value of | 2096 You can set any Lisp variable with @code{setq}, but with certain |
2197 the variable. This can be a constant, a variable, or a function call | 2097 variables @code{setq} won't do what you probably want in the |
2198 expression. In @file{.emacs}, constants are used most of the time. They can be: | 2098 @file{.emacs} file. Some variables automatically become buffer-local |
2099 when set with @code{setq}; what you want in @file{.emacs} is to set | |
2100 the default value, using @code{setq-default}. Some customizable minor | |
2101 mode variables do special things to enable the mode when you set them | |
2102 with Customize, but ordinary @code{setq} won't do that; to enable the | |
2103 mode in your @file{.emacs} file, call the minor mode command. The | |
2104 following section has examples of both of these methods. | |
2105 | |
2106 The second argument to @code{setq} is an expression for the new | |
2107 value of the variable. This can be a constant, a variable, or a | |
2108 function call expression. In @file{.emacs}, constants are used most | |
2109 of the time. They can be: | |
2199 | 2110 |
2200 @table @asis | 2111 @table @asis |
2201 @item Numbers: | 2112 @item Numbers: |
2202 Numbers are written in decimal, with an optional initial minus sign. | 2113 Numbers are written in decimal, with an optional initial minus sign. |
2203 | 2114 |
2215 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}. | 2126 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}. |
2216 Backslash and double-quote are the only characters for which backslash | 2127 Backslash and double-quote are the only characters for which backslash |
2217 sequences are mandatory. | 2128 sequences are mandatory. |
2218 | 2129 |
2219 @samp{\C-} can be used as a prefix for a control character, as in | 2130 @samp{\C-} can be used as a prefix for a control character, as in |
2220 @samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for | 2131 @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for |
2221 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for | 2132 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for |
2222 @kbd{Control-Meta-A}.@refill | 2133 @kbd{Control-Meta-A}.@refill |
2223 | 2134 |
2224 @cindex international characters in @file{.emacs} | 2135 @cindex international characters in @file{.emacs} |
2225 @cindex non-ASCII characters in @file{.emacs} | 2136 @cindex non-@acronym{ASCII} characters in @file{.emacs} |
2226 If you want to include non-ASCII characters in strings in your init | 2137 If you want to include non-@acronym{ASCII} characters in strings in your init |
2227 file, you should consider putting a @w{@samp{-*-coding: | 2138 file, you should consider putting a @w{@samp{-*-coding: |
2228 @var{coding-system}-*-}} tag on the first line which states the coding | 2139 @var{coding-system}-*-}} tag on the first line which states the coding |
2229 system used to save your @file{.emacs}, as explained in @ref{Recognize | 2140 system used to save your @file{.emacs}, as explained in @ref{Recognize |
2230 Coding}. This is because the defaults for decoding non-ASCII text might | 2141 Coding}. This is because the defaults for decoding non-@acronym{ASCII} text might |
2231 not yet be set up by the time Emacs reads those parts of your init file | 2142 not yet be set up by the time Emacs reads those parts of your init file |
2232 which use such strings, possibly leading Emacs to decode those strings | 2143 which use such strings, possibly leading Emacs to decode those strings |
2233 incorrectly. | 2144 incorrectly. |
2234 | 2145 |
2235 @item Characters: | 2146 @item Characters: |
2238 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that | 2149 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that |
2239 strings and characters are not interchangeable in Lisp; some contexts | 2150 strings and characters are not interchangeable in Lisp; some contexts |
2240 require one and some contexts require the other. | 2151 require one and some contexts require the other. |
2241 | 2152 |
2242 @xref{Non-ASCII Rebinding}, for information about binding commands to | 2153 @xref{Non-ASCII Rebinding}, for information about binding commands to |
2243 keys which send non-ASCII characters. | 2154 keys which send non-@acronym{ASCII} characters. |
2244 | 2155 |
2245 @item True: | 2156 @item True: |
2246 @code{t} stands for `true'. | 2157 @code{t} stands for `true'. |
2247 | 2158 |
2248 @item False: | 2159 @item False: |
2311 Set up defaults for the Latin-1 character set | 2222 Set up defaults for the Latin-1 character set |
2312 which supports most of the languages of Western Europe. | 2223 which supports most of the languages of Western Europe. |
2313 | 2224 |
2314 @example | 2225 @example |
2315 (set-language-environment "Latin-1") | 2226 (set-language-environment "Latin-1") |
2227 @end example | |
2228 | |
2229 @need 1500 | |
2230 @item | |
2231 Turn off Line Number mode, a global minor mode. | |
2232 | |
2233 @example | |
2234 (line-number-mode 0) | |
2316 @end example | 2235 @end example |
2317 | 2236 |
2318 @need 1500 | 2237 @need 1500 |
2319 @item | 2238 @item |
2320 Turn on Auto Fill mode automatically in Text mode and related modes. | 2239 Turn on Auto Fill mode automatically in Text mode and related modes. |
2384 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. | 2303 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. |
2385 If the function is not interactive, omit the @code{t} or use | 2304 If the function is not interactive, omit the @code{t} or use |
2386 @code{nil}. | 2305 @code{nil}. |
2387 | 2306 |
2388 @item | 2307 @item |
2389 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}. | 2308 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} |
2309 (@pxref{Init Rebinding}). | |
2390 | 2310 |
2391 @example | 2311 @example |
2392 (global-set-key "\C-xl" 'make-symbolic-link) | 2312 (global-set-key "\C-xl" 'make-symbolic-link) |
2393 @end example | 2313 @end example |
2394 | 2314 |
2442 Enable the use of the command @code{narrow-to-region} without confirmation. | 2362 Enable the use of the command @code{narrow-to-region} without confirmation. |
2443 | 2363 |
2444 @example | 2364 @example |
2445 (put 'narrow-to-region 'disabled nil) | 2365 (put 'narrow-to-region 'disabled nil) |
2446 @end example | 2366 @end example |
2367 | |
2368 @item | |
2369 Adjusting the configuration to various platforms and Emacs versions. | |
2370 | |
2371 Users typically want Emacs to behave the same on all systems, so the | |
2372 same init file is right for all platforms. However, sometimes it | |
2373 happens that a function you use for customizing Emacs is not available | |
2374 on some platforms or in older Emacs versions. To deal with that | |
2375 situation, put the customization inside a conditional that tests whether | |
2376 the function or facility is available, like this: | |
2377 | |
2378 @example | |
2379 (if (fboundp 'blink-cursor-mode) | |
2380 (blink-cursor-mode 0)) | |
2381 | |
2382 (if (boundp 'coding-category-utf-8) | |
2383 (set-coding-priority '(coding-category-utf-8))) | |
2384 @end example | |
2385 | |
2386 @noindent | |
2387 You can also simply disregard the errors that occur if the | |
2388 function is not defined. | |
2389 | |
2390 @example | |
2391 (condition case () | |
2392 (set-face-background 'region "grey75") | |
2393 (error nil)) | |
2394 @end example | |
2395 | |
2396 A @code{setq} on a variable which does not exist is generally | |
2397 harmless, so those do not need a conditional. | |
2447 @end itemize | 2398 @end itemize |
2448 | 2399 |
2449 @node Terminal Init | 2400 @node Terminal Init |
2450 @subsection Terminal-specific Initialization | 2401 @subsection Terminal-specific Initialization |
2451 | 2402 |
2487 | 2438 |
2488 @node Find Init | 2439 @node Find Init |
2489 @subsection How Emacs Finds Your Init File | 2440 @subsection How Emacs Finds Your Init File |
2490 | 2441 |
2491 Normally Emacs uses the environment variable @env{HOME} to find | 2442 Normally Emacs uses the environment variable @env{HOME} to find |
2492 @file{.emacs}; that's what @samp{~} means in a file name. But if you | 2443 @file{.emacs}; that's what @samp{~} means in a file name. If |
2493 run Emacs from a shell started by @code{su}, Emacs tries to find your | 2444 @file{.emacs} is not found inside @file{~/} (nor @file{.emacs.el}), |
2494 own @file{.emacs}, not that of the user you are currently pretending | 2445 Emacs looks for @file{~/.emacs.d/init.el} (which, like |
2495 to be. The idea is that you should get your own editor customizations | 2446 @file{~/.emacs.el}, can be byte-compiled). |
2496 even if you are running as the super user. | 2447 |
2448 However, if you run Emacs from a shell started by @code{su}, Emacs | |
2449 tries to find your own @file{.emacs}, not that of the user you are | |
2450 currently pretending to be. The idea is that you should get your own | |
2451 editor customizations even if you are running as the super user. | |
2497 | 2452 |
2498 More precisely, Emacs first determines which user's init file to use. | 2453 More precisely, Emacs first determines which user's init file to use. |
2499 It gets the user name from the environment variables @env{LOGNAME} and | 2454 It gets the user name from the environment variables @env{LOGNAME} and |
2500 @env{USER}; if neither of those exists, it uses effective user-ID. | 2455 @env{USER}; if neither of those exists, it uses effective user-ID. |
2501 If that user name matches the real user-ID, then Emacs uses @env{HOME}; | 2456 If that user name matches the real user-ID, then Emacs uses @env{HOME}; |
2502 otherwise, it looks up the home directory corresponding to that user | 2457 otherwise, it looks up the home directory corresponding to that user |
2503 name in the system's data base of users. | 2458 name in the system's data base of users. |
2504 @c LocalWords: backtab | 2459 @c LocalWords: backtab |
2460 | |
2461 @ignore | |
2462 arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 | |
2463 @end ignore |