Mercurial > emacs
annotate man/custom.texi @ 38212:6b14cc47a4f2
Major rewrite. Sections Tags, Emerge, Change Log and Authors
moved to maintaining.texi. Some sections reordered.
Node Misc for Programs moved to just before the language-specific sections.
New node Defuns contains an intro plus the old
Defuns node (now renamed Moving by Defuns)
as well as Imenu, Which Function, and a node
Left Margin Paren to explain the convention about this.
New node Parentheses now documents M-x check-parens.
It contains subnodes Expressions, Moving by Parens, and Matching.
Expressions and Moving by Parens contain the material
formerly in Lists and List Commands, but divided up differently.
The section Balanced Editing has been deleted.
Most of the C indentation customization (all except c-set-style),
has been replaced with a reference to the C Modes manual.
Documentation now is divided into three subsections.
Some rewrites in the Program Indent section about
C-u TAB and C-M-q.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 26 Jun 2001 13:43:32 +0000 |
parents | 4face9462576 |
children | 245114062ee0 |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
28126 | 2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 |
3 @c Free Software Foundation, Inc. | |
25829 | 4 @c See file emacs.texi for copying conditions. |
5 @node Customization, Quitting, Amusements, Top | |
6 @chapter Customization | |
7 @cindex customization | |
8 | |
9 This chapter talks about various topics relevant to adapting the | |
10 behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference | |
11 Manual} for how to make more far-reaching changes. | |
12 | |
13 All kinds of customization affect only the particular Emacs session | |
14 that you do them in. They are completely lost when you kill the Emacs | |
15 session, and have no effect on other Emacs sessions you may run at the | |
16 same time or later. The only way an Emacs session can affect anything | |
17 outside of it is by writing a file; in particular, the only way to make | |
18 a customization ``permanent'' is to put something in your @file{.emacs} | |
19 file or other appropriate file to do the customization in each session. | |
20 @xref{Init File}. | |
21 | |
22 @menu | |
23 * Minor Modes:: Each minor mode is one feature you can turn on | |
24 independently of any others. | |
25 * Variables:: Many Emacs commands examine Emacs variables | |
26 to decide what to do; by setting variables, | |
27 you can control their functioning. | |
28 * Keyboard Macros:: A keyboard macro records a sequence of | |
29 keystrokes to be replayed with a single | |
30 command. | |
31 * Key Bindings:: The keymaps say what command each key runs. | |
32 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 | |
38 expressions are parsed. | |
39 * Init File:: How to write common customizations in the | |
40 @file{.emacs} file. | |
41 @end menu | |
42 | |
43 @node Minor Modes | |
44 @section Minor Modes | |
45 @cindex minor modes | |
46 @cindex mode, minor | |
47 | |
48 Minor modes are optional features which you can turn on or off. For | |
49 example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines | |
50 between words as you type. All the minor modes are independent of each | |
51 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 | |
53 that Auto Fill mode is on. | |
54 | |
55 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 | |
57 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These | |
58 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 | |
60 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 | |
62 negative argument always turns it off. | |
63 | |
64 Enabling or disabling some minor modes applies only to the current | |
65 buffer; each buffer is independent of the other buffers. Therefore, you | |
66 can enable the mode in particular buffers and disable it in others. The | |
67 per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save | |
28126 | 68 mode, Font-Lock mode, ISO Accents mode, Outline minor |
25829 | 69 mode, Overwrite mode, and Binary Overwrite mode. |
70 | |
71 Abbrev mode allows you to define abbreviations that automatically expand | |
72 as you type them. For example, @samp{amd} might expand to @samp{abbrev | |
73 mode}. @xref{Abbrevs}, for full information. | |
74 | |
75 Auto Fill mode allows you to enter filled text without breaking lines | |
76 explicitly. Emacs inserts newlines as necessary to prevent lines from | |
77 becoming too long. @xref{Filling}. | |
78 | |
79 Auto Save mode causes the contents of a buffer to be saved | |
80 periodically to reduce the amount of work you can lose in case of a | |
81 system crash. @xref{Auto Save}. | |
82 | |
83 Enriched mode enables editing and saving of formatted text. | |
84 @xref{Formatted Text}. | |
85 | |
86 Flyspell mode automatically highlights misspelled words. | |
87 @xref{Spelling}. | |
88 | |
89 Font-Lock mode automatically highlights certain textual units found in | |
90 programs, such as comments, strings, and function names being defined. | |
91 This requires a window system that can display multiple fonts. | |
92 @xref{Faces}. | |
93 | |
94 ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"}, | |
95 @samp{^}, @samp{/} and @samp{~} combine with the following letter, to | |
96 produce an accented letter in the ISO Latin-1 character set. | |
27218 | 97 @xref{Single-Byte Character Support}. |
25829 | 98 |
99 Outline minor mode provides the same facilities as the major mode | |
100 called Outline mode; but since it is a minor mode instead, you can | |
101 combine it with any major mode. @xref{Outline Mode}. | |
102 | |
103 @cindex Overwrite mode | |
104 @cindex mode, Overwrite | |
105 Overwrite mode causes ordinary printing characters to replace existing | |
106 text instead of shoving it to the right. For example, if point is in | |
107 front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a | |
108 @kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR} | |
109 as usual. In Overwrite mode, the command @kbd{C-q} inserts the next | |
110 character whatever it may be, even if it is a digit---this gives you a | |
111 way to insert a character instead of replacing an existing character. | |
112 | |
37571
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
113 @findex overwrite-mode |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
114 @kindex INSERT |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
115 The command @code{overwrite-mode} is an exception to the rule that |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
116 commands which toggle minor modes are normally not bound to keys: it is |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
117 bound to the @key{INSERT} function key. This is because many other |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
118 programs bind @key{INSERT} to similar functions. |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
119 |
9628e53b601d
Document that overwrite-mode is bound to INSERT and add @kindex for INSERT.
Eli Zaretskii <eliz@gnu.org>
parents:
37419
diff
changeset
|
120 @findex binary-overwrite-mode |
25829 | 121 Binary Overwrite mode is a variant of Overwrite mode for editing |
122 binary files; it treats newlines and tabs like other characters, so that | |
123 they overwrite other characters and can be overwritten by them. | |
37843
e8365cfcb741
Explain how Binary Overwrite mode affects C-q.
Richard M. Stallman <rms@gnu.org>
parents:
37618
diff
changeset
|
124 In Binary Overwrite mode, digits after @kbd{C-q} specify an |
e8365cfcb741
Explain how Binary Overwrite mode affects C-q.
Richard M. Stallman <rms@gnu.org>
parents:
37618
diff
changeset
|
125 octal character code, as usual. |
25829 | 126 |
127 The following minor modes normally apply to all buffers at once. | |
128 Since each is enabled or disabled by the value of a variable, you | |
129 @emph{can} set them differently for particular buffers, by explicitly | |
130 making the corresponding variables local in those buffers. | |
131 @xref{Locals}. | |
132 | |
133 Icomplete mode displays an indication of available completions when | |
134 you are in the minibuffer and completion is active. @xref{Completion | |
135 Options}. | |
136 | |
137 Line Number mode enables continuous display in the mode line of the | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
138 line number of point, and Column Number mode enables display of the |
28126 | 139 column number. @xref{Mode Line}. |
25829 | 140 |
141 Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}). | |
142 Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of | |
143 these modes are enabled by default when you use the X Window System. | |
144 | |
145 In Transient Mark mode, every change in the buffer contents | |
146 ``deactivates'' the mark, so that commands that operate on the region | |
147 will get an error. This means you must either set the mark, or | |
148 explicitly ``reactivate'' it, before each command that uses the region. | |
149 The advantage of Transient Mark mode is that Emacs can display the | |
28126 | 150 region highlighted (currently only when using X). @xref{Mark}. |
25829 | 151 |
152 For most minor modes, the command name is also the name of a variable | |
153 which directly controls the mode. The mode is enabled whenever this | |
154 variable's value is non-@code{nil}, and the minor-mode command works by | |
155 setting the variable. For example, the command | |
156 @code{outline-minor-mode} works by setting the value of | |
157 @code{outline-minor-mode} as a variable; it is this variable that | |
158 directly turns Outline minor mode on and off. To check whether a given | |
159 minor mode works this way, use @kbd{C-h v} to ask for documentation on | |
160 the variable name. | |
161 | |
162 These minor-mode variables provide a good way for Lisp programs to turn | |
163 minor modes on and off; they are also useful in a file's local variables | |
164 list. But please think twice before setting minor modes with a local | |
165 variables list, because most minor modes are matter of user | |
166 preference---other users editing the same file might not want the same | |
167 minor modes you prefer. | |
168 | |
169 @node Variables | |
170 @section Variables | |
171 @cindex variable | |
172 @cindex option, user | |
173 @cindex user option | |
174 | |
175 A @dfn{variable} is a Lisp symbol which has a value. The symbol's | |
176 name is also called the name of the variable. A variable name can | |
177 contain any characters that can appear in a file, but conventionally | |
178 variable names consist of words separated by hyphens. A variable can | |
179 have a documentation string which describes what kind of value it should | |
180 have and how the value will be used. | |
181 | |
182 Lisp allows any variable to have any kind of value, but most variables | |
183 that Emacs uses require a value of a certain type. Often the value should | |
184 always be a string, or should always be a number. Sometimes we say that a | |
185 certain feature is turned on if a variable is ``non-@code{nil},'' meaning | |
186 that if the variable's value is @code{nil}, the feature is off, but the | |
187 feature is on for @emph{any} other value. The conventional value to use to | |
188 turn on the feature---since you have to pick one particular value when you | |
189 set the variable---is @code{t}. | |
190 | |
191 Emacs uses many Lisp variables for internal record keeping, as any | |
192 Lisp program must, but the most interesting variables for you are the | |
193 ones that exist for the sake of customization. Emacs does not (usually) | |
194 change the values of these variables; instead, you set the values, and | |
195 thereby alter and control the behavior of certain Emacs commands. These | |
196 variables are called @dfn{user options}. Most user options are | |
197 documented in this manual, and appear in the Variable Index | |
198 (@pxref{Variable Index}). | |
199 | |
200 One example of a variable which is a user option is @code{fill-column}, which | |
201 specifies the position of the right margin (as a number of characters from | |
202 the left margin) to be used by the fill commands (@pxref{Filling}). | |
203 | |
204 @menu | |
205 * Examining:: Examining or setting one variable's value. | |
206 * Easy Customization:: | |
207 Convenient and easy customization of variables. | |
208 * Hooks:: Hook variables let you specify programs for parts | |
209 of Emacs to run on particular occasions. | |
210 * Locals:: Per-buffer values of variables. | |
211 * File Variables:: How files can specify variable values. | |
212 @end menu | |
213 | |
214 @node Examining | |
215 @subsection Examining and Setting Variables | |
216 @cindex setting variables | |
217 | |
218 @table @kbd | |
219 @item C-h v @var{var} @key{RET} | |
220 Display the value and documentation of variable @var{var} | |
221 (@code{describe-variable}). | |
222 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} | |
223 Change the value of variable @var{var} to @var{value}. | |
224 @end table | |
225 | |
226 To examine the value of a single variable, use @kbd{C-h v} | |
227 (@code{describe-variable}), which reads a variable name using the | |
228 minibuffer, with completion. It displays both the value and the | |
229 documentation of the variable. For example, | |
230 | |
231 @example | |
232 C-h v fill-column @key{RET} | |
233 @end example | |
234 | |
235 @noindent | |
236 displays something like this: | |
237 | |
238 @smallexample | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
239 fill-column's value is 70 |
25829 | 240 |
241 Documentation: | |
242 *Column beyond which automatic line-wrapping should happen. | |
243 Automatically becomes buffer-local when set in any fashion. | |
244 @end smallexample | |
245 | |
246 @noindent | |
247 The star at the beginning of the documentation indicates that this | |
248 variable is a user option. @kbd{C-h v} is not restricted to user | |
249 options; it allows any variable name. | |
250 | |
251 @findex set-variable | |
252 The most convenient way to set a specific user option is with @kbd{M-x | |
253 set-variable}. This reads the variable name with the minibuffer (with | |
254 completion), and then reads a Lisp expression for the new value using | |
255 the minibuffer a second time. For example, | |
256 | |
257 @example | |
258 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
259 @end example | |
260 | |
261 @noindent | |
262 sets @code{fill-column} to 75. | |
263 | |
264 @kbd{M-x set-variable} is limited to user option variables, but you can | |
265 set any variable with a Lisp expression, using the function @code{setq}. | |
266 Here is a @code{setq} expression to set @code{fill-column}: | |
267 | |
268 @example | |
269 (setq fill-column 75) | |
270 @end example | |
271 | |
272 To execute an expression like this one, go to the @samp{*scratch*} | |
273 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp | |
274 Interaction}. | |
275 | |
276 Setting variables, like all means of customizing Emacs except where | |
277 otherwise stated, affects only the current Emacs session. | |
278 | |
279 @node Easy Customization | |
280 @subsection Easy Customization Interface | |
281 | |
282 @findex customize | |
283 @cindex customization buffer | |
284 A convenient way to find the user option variables that you want to | |
285 change, and then change them, is with @kbd{M-x customize}. This command | |
286 creates a @dfn{customization buffer} with which you can browse through | |
287 the Emacs user options in a logically organized structure, then edit and | |
288 set their values. You can also use the customization buffer to save | |
289 settings permanently. (Not all Emacs user options are included in this | |
290 structure as of yet, but we are adding the rest.) | |
291 | |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
292 The appearance of the example buffers in the following is typically |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
293 different under a window system where faces can be used to indicate the |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
294 active fields and other features. |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
295 |
25829 | 296 @menu |
297 * Groups: Customization Groups. | |
298 How options are classified in a structure. | |
299 * Changing an Option:: How to edit a value and set an option. | |
300 * Face Customization:: How to edit the attributes of a face. | |
301 * Specific Customization:: Making a customization buffer for specific | |
302 options, faces, or groups. | |
303 @end menu | |
304 | |
305 @node Customization Groups | |
306 @subsubsection Customization Groups | |
307 @cindex customization groups | |
308 | |
309 For customization purposes, user options are organized into | |
310 @dfn{groups} to help you find them. Groups are collected into bigger | |
311 groups, all the way up to a master group called @code{Emacs}. | |
312 | |
313 @kbd{M-x customize} creates a customization buffer that shows the | |
314 top-level @code{Emacs} group and the second-level groups immediately | |
315 under it. It looks like this, in part: | |
316 | |
317 @smallexample | |
318 /- Emacs group: ---------------------------------------------------\ | |
319 [State]: visible group members are all at standard settings. | |
320 Customization of the One True Editor. | |
321 See also [Manual]. | |
322 | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
323 Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
324 [State]: this option is unchanged from its standard setting. |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
325 How to ask for confirmation when leaving Emacs. [More] |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
326 |
25829 | 327 Editing group: [Go to Group] |
328 Basic text editing facilities. | |
329 | |
330 External group: [Go to Group] | |
331 Interfacing to external utilities. | |
332 | |
333 @var{more second-level groups} | |
334 | |
335 \- Emacs group end ------------------------------------------------/ | |
336 | |
337 @end smallexample | |
338 | |
339 @noindent | |
340 This says that the buffer displays the contents of the @code{Emacs} | |
341 group. The other groups are listed because they are its contents. But | |
342 they are listed differently, without indentation and dashes, because | |
343 @emph{their} contents are not included. Each group has a single-line | |
344 documentation string; the @code{Emacs} group also has a @samp{[State]} | |
345 line. | |
346 | |
347 @cindex editable fields (customization buffer) | |
348 @cindex active fields (customization buffer) | |
349 Most of the text in the customization buffer is read-only, but it | |
350 typically includes some @dfn{editable fields} that you can edit. There | |
351 are also @dfn{active fields}; this means a field that does something | |
352 when you @dfn{invoke} it. To invoke an active field, either click on it | |
353 with @kbd{Mouse-1}, or move point to it and type @key{RET}. | |
354 | |
355 For example, the phrase @samp{[Go to Group]} that appears in a | |
356 second-level group is an active field. Invoking the @samp{[Go to | |
357 Group]} field for a group creates a new customization buffer, which | |
358 shows that group and its contents. This field is a kind of hypertext | |
359 link to another group. | |
360 | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
361 The @code{Emacs} group includes a few user options itself, but most |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
362 of them are in other groups. By examining various groups, you will |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
363 eventually find the options and faces that belong to the feature you |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
364 are interested in customizing. Then you can use the customization |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
365 buffer to set them. You can go straight to a particular group by name |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
366 using the command @kbd{M-x customize-group}. |
25829 | 367 |
368 @findex customize-browse | |
369 You can view the structure of customization groups on a larger scale | |
370 with @kbd{M-x customize-browse}. This command creates a special kind of | |
371 customization buffer which shows only the names of the groups (and | |
372 options and faces), and their structure. | |
373 | |
374 In this buffer, you can show the contents of a group by invoking | |
375 @samp{[+]}. When the group contents are visible, this button changes to | |
376 @samp{[-]}; invoking that hides the group contents. | |
377 | |
378 Each group, option or face name in this buffer has an active field | |
379 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking | |
380 that active field creates an ordinary customization buffer showing just | |
381 that group and its contents, just that option, or just that face. | |
382 This is the way to set values in it. | |
383 | |
384 @node Changing an Option | |
385 @subsubsection Changing an Option | |
386 | |
387 Here is an example of what a user option looks like in the | |
388 customization buffer: | |
389 | |
390 @smallexample | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
391 Kill Ring Max: [Hide] 60 |
25829 | 392 [State]: this option is unchanged from its standard setting. |
393 Maximum length of kill ring before oldest elements are thrown away. | |
394 @end smallexample | |
395 | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
396 The text following @samp{[Hide]}, @samp{60} in this case, indicates |
25829 | 397 the current value of the option. If you see @samp{[Show]} instead of |
398 @samp{[Hide]}, it means that the value is hidden; the customization | |
399 buffer initially hides values that take up several lines. Invoke | |
400 @samp{[Show]} to show the value. | |
401 | |
402 The line after the option name indicates the @dfn{customization state} | |
403 of the option: in the example above, it says you have not changed the | |
404 option yet. The word @samp{[State]} at the beginning of this line is | |
405 active; you can get a menu of various operations by invoking it with | |
406 @kbd{Mouse-1} or @key{RET}. These operations are essential for | |
407 customizing the variable. | |
408 | |
409 The line after the @samp{[State]} line displays the beginning of the | |
410 option's documentation string. If there are more lines of | |
411 documentation, this line ends with @samp{[More]}; invoke this to show | |
412 the full documentation string. | |
413 | |
414 To enter a new value for @samp{Kill Ring Max}, move point to the value | |
415 and edit it textually. For example, you can type @kbd{M-d}, then insert | |
416 another number. | |
417 | |
418 When you begin to alter the text, you will see the @samp{[State]} line | |
419 change to say that you have edited the value: | |
420 | |
421 @smallexample | |
422 [State]: you have edited the value as text, but not set the option. | |
423 @end smallexample | |
424 | |
425 @cindex setting option value | |
426 Editing the value does not actually set the option variable. To do | |
427 that, you must @dfn{set} the option. To do this, invoke the word | |
428 @samp{[State]} and choose @samp{Set for Current Session}. | |
429 | |
430 The state of the option changes visibly when you set it: | |
431 | |
432 @smallexample | |
433 [State]: you have set this option, but not saved it for future sessions. | |
434 @end smallexample | |
435 | |
436 You don't have to worry about specifying a value that is not valid; | |
437 setting the option checks for validity and will not really install an | |
438 unacceptable value. | |
439 | |
440 @kindex M-TAB @r{(customization buffer)} | |
441 @findex widget-complete | |
442 While editing a value or field that is a file name, directory name, | |
443 command name, or anything else for which completion is defined, you can | |
444 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. | |
445 | |
446 Some options have a small fixed set of possible legitimate values. | |
447 These options don't let you edit the value textually. Instead, an | |
448 active field @samp{[Value Menu]} appears before the value; invoke this | |
449 field to edit the value. For a boolean ``on or off'' value, the active | |
450 field says @samp{[Toggle]}, and it changes to the other value. | |
451 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes | |
452 take effect when you use the @samp{Set for Current Session} operation. | |
453 | |
454 Some options have values with complex structure. For example, the | |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
455 value of @code{file-coding-system-alist} is an association list. Here |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
456 is how it appears in the customization buffer: |
25829 | 457 |
458 @smallexample | |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
459 File Coding System Alist: [Hide] |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
460 [INS] [DEL] File regexp: \.elc\' |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
461 Choice: [Value Menu] Encoding/decoding pair: |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
462 Decoding: emacs-mule |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
463 Encoding: emacs-mule |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
464 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
465 Choice: [Value Menu] Encoding/decoding pair: |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
466 Decoding: raw-text |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
467 Encoding: raw-text-unix |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
468 [INS] [DEL] File regexp: \.tar\' |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
469 Choice: [Value Menu] Encoding/decoding pair: |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
470 Decoding: no-conversion |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
471 Encoding: no-conversion |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
472 [INS] [DEL] File regexp: |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
473 Choice: [Value Menu] Encoding/decoding pair: |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
474 Decoding: undecided |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
475 Encoding: nil |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
476 [INS] |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
477 [State]: this option is unchanged from its standard setting. |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
478 Alist to decide a coding system to use for a file I/O operation. [Hide] |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
479 The format is ((PATTERN . VAL) ...), |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
480 where PATTERN is a regular expression matching a file name, |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
481 @r{[@dots{}more lines of documentation@dots{}]} |
25829 | 482 @end smallexample |
483 | |
484 @noindent | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
485 Each association in the list appears on four lines, with several |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
486 editable or ``active'' fields. You can edit the regexps and coding |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
487 systems using ordinary editing commands. You can also invoke |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
488 @samp{[Value Menu]} to switch to a kind of value---for instance, to |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
489 specify a function instead of a pair of coding systems. |
25829 | 490 |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
491 To delete an association from the list, invoke the @samp{[DEL]} button |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
492 for that item. To add an association, invoke @samp{[INS]} at the |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
493 position where you want to add it. There is an @samp{[INS]} button |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
494 between each pair of association, another at the beginning and another |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
495 at the end, so you can add the new association at any position in the |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
496 list. |
25829 | 497 |
498 @kindex TAB @r{(customization buffer)} | |
499 @kindex S-TAB @r{(customization buffer)} | |
500 @findex widget-forward | |
501 @findex widget-backward | |
502 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for | |
503 moving through the customization buffer. @key{TAB} | |
504 (@code{widget-forward}) moves forward to the next active or editable | |
505 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the | |
506 previous active or editable field. | |
507 | |
508 Typing @key{RET} on an editable field also moves forward, just like | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
509 @key{TAB}. We set it up this way because people often type @key{RET} |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
510 when they are finished editing a field. To insert a newline within an |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
511 editable field, use @kbd{C-o} or @kbd{C-q C-j}. |
25829 | 512 |
513 @cindex saving option value | |
37618
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
514 @cindex customized options, saving |
25829 | 515 Setting the option changes its value in the current Emacs session; |
516 @dfn{saving} the value changes it for future sessions as well. This | |
517 works by writing code into your @file{~/.emacs} file so as to set the | |
518 option variable again each time you start Emacs. To save the option, | |
519 invoke @samp{[State]} and select the @samp{Save for Future Sessions} | |
520 operation. | |
521 | |
37618
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
522 If Emacs was invoked with the @option{-q} or @option{--no-init-file} |
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
523 options (@pxref{Initial Options}), it will not let you save your |
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
524 customizations in your @file{~/.emacs} init file. This is because |
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
525 saving customizations from such a session would wipe out all the other |
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
526 customizations you might have on your init file. |
764853859fbc
(Changing an Option): Document that "emacs -q" cannot save customizations.
Eli Zaretskii <eliz@gnu.org>
parents:
37596
diff
changeset
|
527 |
25829 | 528 You can also restore the option to its standard value by invoking |
27218 | 529 @samp{[State]} and selecting the @samp{Erase Customization} |
25829 | 530 operation. There are actually three reset operations: |
531 | |
532 @table @samp | |
533 @item Reset | |
534 If you have made some modifications and not yet set the option, | |
535 this restores the text in the customization buffer to match | |
536 the actual value. | |
537 | |
538 @item Reset to Saved | |
539 This restores the value of the option to the last saved value, | |
540 and updates the text accordingly. | |
541 | |
27218 | 542 @item Erase Customization |
25829 | 543 This sets the option to its standard value, and updates the text |
544 accordingly. This also eliminates any saved value for the option, | |
545 so that you will get the standard value in future Emacs sessions. | |
546 @end table | |
547 | |
27218 | 548 @cindex comments on customized options |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
549 Sometimes it is useful to record a comment about a specific |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
550 customization. Use the @samp{Add Comment} item from the |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
551 @samp{[State]} menu to create a field for entering the comment. The |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
552 comment you enter will be saved, and displayed again if you again view |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
553 the same option in a customization buffer, even in another session. |
27218 | 554 |
25829 | 555 The state of a group indicates whether anything in that group has been |
556 edited, set or saved. You can select @samp{Set for Current Session}, | |
557 @samp{Save for Future Sessions} and the various kinds of @samp{Reset} | |
558 operation for the group; these operations on the group apply to all | |
559 options in the group and its subgroups. | |
560 | |
561 Near the top of the customization buffer there are two lines | |
562 containing several active fields: | |
563 | |
564 @smallexample | |
565 [Set for Current Session] [Save for Future Sessions] | |
27218 | 566 [Reset] [Reset to Saved] [Erase Customization] [Finish] |
25829 | 567 @end smallexample |
568 | |
36593
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
569 @vindex custom-buffer-done-function |
25829 | 570 @noindent |
27218 | 571 Invoking @samp{[Finish]} either buries or kills this customization |
36593
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
572 buffer according to the setting of the option |
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
573 @code{custom-buffer-done-function}; the default is to bury the buffer. |
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
574 Each of the other fields performs an operation---set, save or |
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
575 reset---on each of the items in the buffer that could meaningfully be |
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
576 set, saved or reset. |
25829 | 577 |
578 @node Face Customization | |
579 @subsubsection Customizing Faces | |
580 @cindex customizing faces | |
581 @cindex bold font | |
582 @cindex italic font | |
583 @cindex fonts and faces | |
584 | |
585 In addition to user options, some customization groups also include | |
586 faces. When you show the contents of a group, both the user options and | |
587 the faces in the group appear in the customization buffer. Here is an | |
588 example of how a face looks: | |
589 | |
590 @smallexample | |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
591 Custom Changed Face: (sample) [Hide] |
25829 | 592 [State]: this face is unchanged from its standard setting. |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
593 Parent groups: [Custom Magic Faces] |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
594 Attributes: [ ] Font family: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
595 [ ] Width: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
596 [ ] Height: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
597 [ ] Weight: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
598 [ ] Slant: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
599 [ ] Underline: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
600 [ ] Overline: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
601 [ ] Strike-through: [Value Menu] * |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
602 [ ] Box around text: [Value Menu] * |
31075
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
603 [ ] Inverse-video: [Value Menu] * |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
604 [X] Foreground: [Value Menu] Color: white (sample) |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
605 [X] Background: [Value Menu] Color: blue (sample) |
9c560a17ef4a
(Changing an Option): Change load-path example.
Dave Love <fx@gnu.org>
parents:
29107
diff
changeset
|
606 [ ] Stipple: [Value Menu] * |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
607 [ ] Inherit: |
25829 | 608 @end smallexample |
609 | |
610 Each face attribute has its own line. The @samp{[@var{x}]} field | |
611 before the attribute name indicates whether the attribute is | |
612 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the | |
613 attribute by invoking that field. When the attribute is enabled, you | |
614 can change the attribute value in the usual ways. | |
615 | |
616 On a black-and-white display, the colors you can use for the | |
617 background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, | |
618 and @samp{gray3}. Emacs supports these shades of gray by using | |
619 background stipple patterns instead of a color. | |
620 | |
621 Setting, saving and resetting a face work like the same operations for | |
622 options (@pxref{Changing an Option}). | |
623 | |
624 A face can specify different appearances for different types of | |
625 display. For example, a face can make text red on a color display, but | |
626 use a bold font on a monochrome display. To specify multiple | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
627 appearances for a face, select @samp{Show all display specs} in the menu you |
25829 | 628 get from invoking @samp{[State]}. |
629 | |
630 @findex modify-face | |
631 Another more basic way to set the attributes of a specific face is | |
632 with @kbd{M-x modify-face}. This command reads the name of a face, then | |
633 reads the attributes one by one. For the color and stipple attributes, | |
634 the attribute's current value is the default---type just @key{RET} if | |
635 you don't want to change that attribute. Type @samp{none} if you want | |
636 to clear out the attribute. | |
637 | |
638 @node Specific Customization | |
639 @subsubsection Customizing Specific Items | |
640 | |
641 Instead of finding the options you want to change by moving down | |
642 through the structure of groups, you can specify the particular option, | |
643 face or group that you want to customize. | |
644 | |
645 @table @kbd | |
646 @item M-x customize-option @key{RET} @var{option} @key{RET} | |
647 Set up a customization buffer with just one option, @var{option}. | |
648 @item M-x customize-face @key{RET} @var{face} @key{RET} | |
649 Set up a customization buffer with just one face, @var{face}. | |
650 @item M-x customize-group @key{RET} @var{group} @key{RET} | |
651 Set up a customization buffer with just one group, @var{group}. | |
652 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET} | |
653 Set up a customization buffer with all the options, faces and groups | |
654 that match @var{regexp}. | |
655 @item M-x customize-changed-options @key{RET} @var{version} @key{RET} | |
656 Set up a customization buffer with all the options, faces and groups | |
657 whose meaning has changed since Emacs version @var{version}. | |
658 @item M-x customize-saved | |
659 Set up a customization buffer containing all options and faces that you | |
660 have saved with customization buffers. | |
661 @item M-x customize-customized | |
662 Set up a customization buffer containing all options and faces that you | |
663 have customized but not saved. | |
664 @end table | |
665 | |
666 @findex customize-option | |
667 If you want to alter a particular user option variable with the | |
668 customization buffer, and you know its name, you can use the command | |
669 @kbd{M-x customize-option} and specify the option name. This sets up | |
670 the customization buffer with just one option---the one that you asked | |
671 for. Editing, setting and saving the value work as described above, but | |
672 only for the specified option. | |
673 | |
674 @findex customize-face | |
675 Likewise, you can modify a specific face, chosen by name, using | |
676 @kbd{M-x customize-face}. | |
677 | |
678 @findex customize-group | |
679 You can also set up the customization buffer with a specific group, | |
680 using @kbd{M-x customize-group}. The immediate contents of the chosen | |
681 group, including option variables, faces, and other groups, all appear | |
682 as well. However, these subgroups' own contents start out hidden. You | |
683 can show their contents in the usual way, by invoking @samp{[Show]}. | |
684 | |
685 @findex customize-apropos | |
686 To control more precisely what to customize, you can use @kbd{M-x | |
687 customize-apropos}. You specify a regular expression as argument; then | |
688 all options, faces and groups whose names match this regular expression | |
689 are set up in the customization buffer. If you specify an empty regular | |
690 expression, this includes @emph{all} groups, options and faces in the | |
691 customization buffer (but that takes a long time). | |
692 | |
693 @findex customize-changed-options | |
694 When you upgrade to a new Emacs version, you might want to customize | |
695 new options and options whose meanings or default values have changed. | |
696 To do this, use @kbd{M-x customize-changed-options} and specify a | |
697 previous Emacs version number using the minibuffer. It creates a | |
698 customization buffer which shows all the options (and groups) whose | |
699 definitions have been changed since the specified version. | |
700 | |
701 @findex customize-saved | |
702 @findex customize-customized | |
703 If you change option values and then decide the change was a mistake, | |
704 you can use two special commands to revisit your previous changes. Use | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
705 @kbd{M-x customize-saved} to look at the options and faces that you have |
25829 | 706 saved. Use @kbd{M-x customize-customized} to look at the options and |
707 faces that you have set but not saved. | |
708 | |
709 @node Hooks | |
710 @subsection Hooks | |
711 @cindex hook | |
712 @cindex running a hook | |
713 | |
714 @dfn{Hooks} are an important mechanism for customization of Emacs. A | |
715 hook is a Lisp variable which holds a list of functions, to be called on | |
716 some well-defined occasion. (This is called @dfn{running the hook}.) | |
717 The individual functions in the list are called the @dfn{hook functions} | |
718 of the hook. With rare exceptions, hooks in Emacs are empty when Emacs | |
719 starts up, so the only hook functions in any given hook are the ones you | |
720 explicitly put there as customization. | |
721 | |
722 Most major modes run one or more @dfn{mode hooks} as the last step of | |
723 initialization. This makes it easy for you to customize the behavior of | |
724 the mode, by setting up a hook function to override the local variable | |
725 assignments already made by the mode. But hooks are also used in other | |
726 contexts. For example, the hook @code{suspend-hook} runs just before | |
727 Emacs suspends itself (@pxref{Exiting}). | |
728 | |
729 @cindex normal hook | |
730 Most Emacs hooks are @dfn{normal hooks}. This means that running the | |
731 hook operates by calling all the hook functions, unconditionally, with | |
732 no arguments. We have made an effort to keep most hooks normal so that | |
733 you can use them in a uniform way. Every variable in Emacs whose name | |
734 ends in @samp{-hook} is a normal hook. | |
735 | |
736 @cindex abnormal hook | |
737 There are also a few @dfn{abnormal hooks}. These variables' names end | |
738 in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What | |
739 makes these hooks abnormal is that there is something peculiar about the | |
740 way its functions are called---perhaps they are given arguments, or | |
741 perhaps the values they return are used in some way. For example, | |
742 @code{find-file-not-found-hooks} (@pxref{Visiting}) is abnormal because | |
743 as soon as one hook function returns a non-@code{nil} value, the rest | |
744 are not called at all. The documentation of each abnormal hook variable | |
745 explains in detail what is peculiar about it. | |
746 | |
747 The recommended way to add a hook function to a hook (either normal or | |
748 abnormal) is by calling @code{add-hook}. You can use any valid Lisp | |
749 function as the hook function, provided it can handle the proper number | |
750 of arguments (zero arguments, in the case of a normal hook). Of course, | |
751 not every Lisp function is @emph{useful} in any particular hook. | |
752 | |
753 For example, here's how to set up a hook to turn on Auto Fill mode | |
754 when entering Text mode and other modes based on Text mode: | |
755 | |
756 @example | |
757 (add-hook 'text-mode-hook 'turn-on-auto-fill) | |
758 @end example | |
759 | |
760 The next example shows how to use a hook to customize the indentation | |
761 of C code. (People often have strong personal preferences for one | |
762 format compared to another.) Here the hook function is an anonymous | |
763 lambda expression. | |
764 | |
765 @example | |
766 @group | |
767 (setq my-c-style | |
768 '((c-comment-only-line-offset . 4) | |
769 @end group | |
770 @group | |
771 (c-cleanup-list . (scope-operator | |
772 empty-defun-braces | |
773 defun-close-semi)) | |
774 @end group | |
775 @group | |
776 (c-offsets-alist . ((arglist-close . c-lineup-arglist) | |
777 (substatement-open . 0))))) | |
778 @end group | |
779 | |
780 @group | |
781 (add-hook 'c-mode-common-hook | |
36593
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
782 '(lambda () |
4567e1729217
custom-buffer-done-function <- Custom-buffer-done
Dave Love <fx@gnu.org>
parents:
36292
diff
changeset
|
783 (c-add-style "my-style" my-c-style t))) |
25829 | 784 @end group |
785 @end example | |
786 | |
787 It is best to design your hook functions so that the order in which | |
788 they are executed does not matter. Any dependence on the order is | |
789 ``asking for trouble.'' However, the order is predictable: the most | |
790 recently added hook functions are executed first. | |
791 | |
792 @node Locals | |
793 @subsection Local Variables | |
794 | |
795 @table @kbd | |
796 @item M-x make-local-variable @key{RET} @var{var} @key{RET} | |
797 Make variable @var{var} have a local value in the current buffer. | |
798 @item M-x kill-local-variable @key{RET} @var{var} @key{RET} | |
799 Make variable @var{var} use its global value in the current buffer. | |
800 @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} | |
801 Mark variable @var{var} so that setting it will make it local to the | |
802 buffer that is current at that time. | |
803 @end table | |
804 | |
805 @cindex local variables | |
806 Almost any variable can be made @dfn{local} to a specific Emacs | |
807 buffer. This means that its value in that buffer is independent of its | |
808 value in other buffers. A few variables are always local in every | |
809 buffer. Every other Emacs variable has a @dfn{global} value which is in | |
810 effect in all buffers that have not made the variable local. | |
811 | |
812 @findex make-local-variable | |
813 @kbd{M-x make-local-variable} reads the name of a variable and makes it | |
814 local to the current buffer. Further changes in this buffer will not | |
815 affect others, and further changes in the global value will not affect this | |
816 buffer. | |
817 | |
818 @findex make-variable-buffer-local | |
819 @cindex per-buffer variables | |
820 @kbd{M-x make-variable-buffer-local} reads the name of a variable and | |
821 changes the future behavior of the variable so that it will become local | |
822 automatically when it is set. More precisely, once a variable has been | |
823 marked in this way, the usual ways of setting the variable automatically | |
824 do @code{make-local-variable} first. We call such variables | |
825 @dfn{per-buffer} variables. | |
826 | |
827 Major modes (@pxref{Major Modes}) always make variables local to the | |
828 buffer before setting the variables. This is why changing major modes | |
829 in one buffer has no effect on other buffers. Minor modes also work by | |
830 setting variables---normally, each minor mode has one controlling | |
831 variable which is non-@code{nil} when the mode is enabled (@pxref{Minor | |
832 Modes}). For most minor modes, the controlling variable is per buffer. | |
833 | |
834 Emacs contains a number of variables that are always per-buffer. | |
835 These include @code{abbrev-mode}, @code{auto-fill-function}, | |
836 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow}, | |
837 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode}, | |
838 @code{left-margin}, @code{mode-line-format}, @code{overwrite-mode}, | |
839 @code{selective-display-ellipses}, @code{selective-display}, | |
840 @code{tab-width}, and @code{truncate-lines}. Some other variables are | |
841 always local in every buffer, but they are used for internal | |
842 purposes.@refill | |
843 | |
844 A few variables cannot be local to a buffer because they are always | |
845 local to each display instead (@pxref{Multiple Displays}). If you try to | |
846 make one of these variables buffer-local, you'll get an error message. | |
847 | |
848 @findex kill-local-variable | |
849 @kbd{M-x kill-local-variable} reads the name of a variable and makes | |
850 it cease to be local to the current buffer. The global value of the | |
851 variable henceforth is in effect in this buffer. Setting the major mode | |
852 kills all the local variables of the buffer except for a few variables | |
853 specially marked as @dfn{permanent locals}. | |
854 | |
855 @findex setq-default | |
856 To set the global value of a variable, regardless of whether the | |
857 variable has a local value in the current buffer, you can use the Lisp | |
858 construct @code{setq-default}. This construct is used just like | |
859 @code{setq}, but it sets variables' global values instead of their local | |
860 values (if any). When the current buffer does have a local value, the | |
861 new global value may not be visible until you switch to another buffer. | |
862 Here is an example: | |
863 | |
864 @example | |
865 (setq-default fill-column 75) | |
866 @end example | |
867 | |
868 @noindent | |
869 @code{setq-default} is the only way to set the global value of a variable | |
870 that has been marked with @code{make-variable-buffer-local}. | |
871 | |
872 @findex default-value | |
873 Lisp programs can use @code{default-value} to look at a variable's | |
874 default value. This function takes a symbol as argument and returns its | |
875 default value. The argument is evaluated; usually you must quote it | |
876 explicitly. For example, here's how to obtain the default value of | |
877 @code{fill-column}: | |
878 | |
879 @example | |
880 (default-value 'fill-column) | |
881 @end example | |
882 | |
883 @node File Variables | |
884 @subsection Local Variables in Files | |
885 @cindex local variables in files | |
886 @cindex file local variables | |
887 | |
888 A file can specify local variable values for use when you edit the | |
889 file with Emacs. Visiting the file checks for local variable | |
890 specifications; it automatically makes these variables local to the | |
891 buffer, and sets them to the values specified in the file. | |
892 | |
893 There are two ways to specify local variable values: in the first | |
894 line, or with a local variables list. Here's how to specify them in the | |
895 first line: | |
896 | |
897 @example | |
898 -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- | |
899 @end example | |
900 | |
901 @noindent | |
902 You can specify any number of variables/value pairs in this way, each | |
903 pair with a colon and semicolon as shown above. @code{mode: | |
904 @var{modename};} specifies the major mode; this should come first in the | |
905 line. The @var{value}s are not evaluated; they are used literally. | |
906 Here is an example that specifies Lisp mode and sets two variables with | |
907 numeric values: | |
908 | |
909 @smallexample | |
36632
1bfc2fad762a
(File Variables): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents:
36593
diff
changeset
|
910 ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- |
25829 | 911 @end smallexample |
912 | |
913 You can also specify the coding system for a file in this way: just | |
914 specify a value for the ``variable'' named @code{coding}. The ``value'' | |
915 must be a coding system name that Emacs recognizes. @xref{Coding | |
916 Systems}. | |
917 | |
34116
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
918 The @code{eval} pseudo-variable, described below, can be specified in |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
919 the first line as well. |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
920 |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
921 @cindex shell scripts, and local file variables |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
922 In shell scripts, the first line is used to identify the script |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
923 interpreter, so you cannot put any local variables there. To accomodate |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
924 for this, when Emacs visits a shell script, it looks for local variable |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
925 specifications in the @emph{second} line. |
1c497211a58d
Docment that `eval' can be used with local variables in the first
Eli Zaretskii <eliz@gnu.org>
parents:
31075
diff
changeset
|
926 |
25829 | 927 A @dfn{local variables list} goes near the end of the file, in the |
928 last page. (It is often best to put it on a page by itself.) The local | |
929 variables list starts with a line containing the string @samp{Local | |
930 Variables:}, and ends with a line containing the string @samp{End:}. In | |
931 between come the variable names and values, one set per line, as | |
932 @samp{@var{variable}:@: @var{value}}. The @var{value}s are not | |
933 evaluated; they are used literally. If a file has both a local | |
934 variables list and a @samp{-*-} line, Emacs processes @emph{everything} | |
935 in the @samp{-*-} line first, and @emph{everything} in the local | |
936 variables list afterward. | |
937 | |
938 Here is an example of a local variables list: | |
939 | |
940 @example | |
941 ;;; Local Variables: *** | |
942 ;;; mode:lisp *** | |
943 ;;; comment-column:0 *** | |
944 ;;; comment-start: ";;; " *** | |
945 ;;; comment-end:"***" *** | |
946 ;;; End: *** | |
947 @end example | |
948 | |
949 As you see, each line starts with the prefix @samp{;;; } and each line | |
950 ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix | |
951 and suffix based on the first line of the list, by finding them | |
952 surrounding the magic string @samp{Local Variables:}; then it | |
953 automatically discards them from the other lines of the list. | |
954 | |
955 The usual reason for using a prefix and/or suffix is to embed the | |
956 local variables list in a comment, so it won't confuse other programs | |
957 that the file is intended as input for. The example above is for a | |
958 language where comment lines start with @samp{;;; } and end with | |
959 @samp{***}; the local values for @code{comment-start} and | |
960 @code{comment-end} customize the rest of Emacs for this unusual syntax. | |
961 Don't use a prefix (or a suffix) if you don't need one. | |
962 | |
963 Two ``variable names'' have special meanings in a local variables | |
964 list: a value for the variable @code{mode} really sets the major mode, | |
965 and a value for the variable @code{eval} is simply evaluated as an | |
966 expression and the value is ignored. @code{mode} and @code{eval} are | |
967 not real variables; setting variables named @code{mode} and @code{eval} | |
968 in any other context has no special meaning. If @code{mode} is used to | |
969 set a major mode, it should be the first ``variable'' in the list. | |
970 | |
971 You can use the @code{mode} ``variable'' to set minor modes as well as | |
972 major modes; in fact, you can use it more than once, first to set the | |
973 major mode and then to set minor modes which are specific to particular | |
974 buffers. But most minor modes should not be specified in the file in | |
975 any fashion, because they represent user preferences. | |
976 | |
977 For example, you may be tempted to try to turn on Auto Fill mode with | |
978 a local variable list. That is a mistake. The choice of Auto Fill mode | |
979 or not is a matter of individual taste, not a matter of the contents of | |
980 particular files. If you want to use Auto Fill, set up major mode hooks | |
981 with your @file{.emacs} file to turn it on (when appropriate) for you | |
982 alone (@pxref{Init File}). Don't use a local variable list to impose | |
983 your taste on everyone. | |
984 | |
985 The start of the local variables list must be no more than 3000 | |
986 characters from the end of the file, and must be in the last page if the | |
987 file is divided into pages. Otherwise, Emacs will not notice it is | |
988 there. The purpose of this rule is so that a stray @samp{Local | |
989 Variables:}@: not in the last page does not confuse Emacs, and so that | |
990 visiting a long file that is all one page and has no local variables | |
991 list need not take the time to search the whole file. | |
992 | |
993 Use the command @code{normal-mode} to reset the local variables and | |
994 major mode of a buffer according to the file name and contents, | |
995 including the local variables list if any. @xref{Choosing Modes}. | |
996 | |
997 @findex enable-local-variables | |
998 The variable @code{enable-local-variables} controls whether to process | |
999 local variables in files, and thus gives you a chance to override them. | |
1000 Its default value is @code{t}, which means do process local variables in | |
1001 files. If you set the value to @code{nil}, Emacs simply ignores local | |
1002 variables in files. Any other value says to query you about each file | |
1003 that has local variables, showing you the local variable specifications | |
1004 so you can judge. | |
1005 | |
1006 @findex enable-local-eval | |
1007 The @code{eval} ``variable,'' and certain actual variables, create a | |
1008 special risk; when you visit someone else's file, local variable | |
1009 specifications for these could affect your Emacs in arbitrary ways. | |
1010 Therefore, the option @code{enable-local-eval} controls whether Emacs | |
1011 processes @code{eval} variables, as well variables with names that end | |
1012 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions}, | |
1013 and certain other variables. The three possibilities for the option's | |
1014 value are @code{t}, @code{nil}, and anything else, just as for | |
1015 @code{enable-local-variables}. The default is @code{maybe}, which is | |
1016 neither @code{t} nor @code{nil}, so normally Emacs does ask for | |
1017 confirmation about file settings for these variables. | |
1018 | |
1019 @node Keyboard Macros | |
1020 @section Keyboard Macros | |
1021 | |
1022 @cindex defining keyboard macros | |
1023 @cindex keyboard macro | |
1024 A @dfn{keyboard macro} is a command defined by the user to stand for | |
1025 another sequence of keys. For example, if you discover that you are | |
1026 about to type @kbd{C-n C-d} forty times, you can speed your work by | |
1027 defining a keyboard macro to do @kbd{C-n C-d} and calling it with a | |
1028 repeat count of forty. | |
1029 | |
1030 @c widecommands | |
1031 @table @kbd | |
1032 @item C-x ( | |
1033 Start defining a keyboard macro (@code{start-kbd-macro}). | |
1034 @item C-x ) | |
1035 End the definition of a keyboard macro (@code{end-kbd-macro}). | |
1036 @item C-x e | |
1037 Execute the most recent keyboard macro (@code{call-last-kbd-macro}). | |
1038 @item C-u C-x ( | |
1039 Re-execute last keyboard macro, then add more keys to its definition. | |
1040 @item C-x q | |
1041 When this point is reached during macro execution, ask for confirmation | |
1042 (@code{kbd-macro-query}). | |
1043 @item M-x name-last-kbd-macro | |
1044 Give a command name (for the duration of the session) to the most | |
1045 recently defined keyboard macro. | |
1046 @item M-x insert-kbd-macro | |
1047 Insert in the buffer a keyboard macro's definition, as Lisp code. | |
1048 @item C-x C-k | |
1049 Edit a previously defined keyboard macro (@code{edit-kbd-macro}). | |
1050 @item M-x apply-macro-to-region-lines | |
1051 Run the last keyboard macro on each complete line in the region. | |
1052 @end table | |
1053 | |
1054 Keyboard macros differ from ordinary Emacs commands in that they are | |
1055 written in the Emacs command language rather than in Lisp. This makes it | |
1056 easier for the novice to write them, and makes them more convenient as | |
1057 temporary hacks. However, the Emacs command language is not powerful | |
1058 enough as a programming language to be useful for writing anything | |
1059 intelligent or general. For such things, Lisp must be used. | |
1060 | |
1061 You define a keyboard macro while executing the commands which are the | |
1062 definition. Put differently, as you define a keyboard macro, the | |
1063 definition is being executed for the first time. This way, you can see | |
1064 what the effects of your commands are, so that you don't have to figure | |
1065 them out in your head. When you are finished, the keyboard macro is | |
1066 defined and also has been, in effect, executed once. You can then do the | |
1067 whole thing over again by invoking the macro. | |
1068 | |
1069 @menu | |
1070 * Basic Kbd Macro:: Defining and running keyboard macros. | |
1071 * Save Kbd Macro:: Giving keyboard macros names; saving them in files. | |
1072 * Kbd Macro Query:: Making keyboard macros do different things each time. | |
1073 @end menu | |
1074 | |
1075 @node Basic Kbd Macro | |
1076 @subsection Basic Use | |
1077 | |
1078 @kindex C-x ( | |
1079 @kindex C-x ) | |
1080 @kindex C-x e | |
1081 @findex start-kbd-macro | |
1082 @findex end-kbd-macro | |
1083 @findex call-last-kbd-macro | |
1084 To start defining a keyboard macro, type the @kbd{C-x (} command | |
1085 (@code{start-kbd-macro}). From then on, your keys continue to be | |
1086 executed, but also become part of the definition of the macro. @samp{Def} | |
1087 appears in the mode line to remind you of what is going on. When you are | |
1088 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the | |
1089 definition (without becoming part of it!). For example, | |
1090 | |
1091 @example | |
1092 C-x ( M-f foo C-x ) | |
1093 @end example | |
1094 | |
1095 @noindent | |
1096 defines a macro to move forward a word and then insert @samp{foo}. | |
1097 | |
1098 The macro thus defined can be invoked again with the @kbd{C-x e} | |
1099 command (@code{call-last-kbd-macro}), which may be given a repeat count | |
1100 as a numeric argument to execute the macro many times. @kbd{C-x )} can | |
1101 also be given a repeat count as an argument, in which case it repeats | |
1102 the macro that many times right after defining it, but defining the | |
1103 macro counts as the first repetition (since it is executed as you define | |
1104 it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro | |
1105 immediately 3 additional times. An argument of zero to @kbd{C-x e} or | |
1106 @kbd{C-x )} means repeat the macro indefinitely (until it gets an error | |
1107 or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}). | |
1108 | |
1109 If you wish to repeat an operation at regularly spaced places in the | |
1110 text, define a macro and include as part of the macro the commands to move | |
1111 to the next place you want to use it. For example, if you want to change | |
1112 each line, you should position point at the start of a line, and define a | |
1113 macro to change that line and leave point at the start of the next line. | |
1114 Then repeating the macro will operate on successive lines. | |
1115 | |
1116 After you have terminated the definition of a keyboard macro, you can add | |
1117 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent | |
1118 to plain @kbd{C-x (} followed by retyping the whole definition so far. As | |
1119 a consequence it re-executes the macro as previously defined. | |
1120 | |
1121 You can use function keys in a keyboard macro, just like keyboard | |
1122 keys. You can even use mouse events, but be careful about that: when | |
1123 the macro replays the mouse event, it uses the original mouse position | |
1124 of that event, the position that the mouse had while you were defining | |
1125 the macro. The effect of this may be hard to predict. (Using the | |
1126 current mouse position would be even less predictable.) | |
1127 | |
1128 One thing that doesn't always work well in a keyboard macro is the | |
1129 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command | |
1130 exits a recursive edit that started within the macro, it works as you'd | |
1131 expect. But if it exits a recursive edit that started before you | |
1132 invoked the keyboard macro, it also necessarily exits the keyboard macro | |
1133 as part of the process. | |
1134 | |
1135 @findex edit-kbd-macro | |
1136 @kindex C-x C-k | |
1137 You can edit a keyboard macro already defined by typing @kbd{C-x C-k} | |
1138 (@code{edit-kbd-macro}). Follow that with the keyboard input that you | |
1139 would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or | |
1140 some other key sequence. This formats the macro definition in a buffer | |
1141 and enters a specialized major mode for editing it. Type @kbd{C-h m} | |
1142 once in that buffer to display details of how to edit the macro. When | |
1143 you are finished editing, type @kbd{C-c C-c}. | |
1144 | |
1145 @findex apply-macro-to-region-lines | |
1146 The command @kbd{M-x apply-macro-to-region-lines} repeats the last | |
1147 defined keyboard macro on each complete line within the current region. | |
1148 It does this line by line, by moving point to the beginning of the line | |
1149 and then executing the macro. | |
1150 | |
1151 @node Save Kbd Macro | |
1152 @subsection Naming and Saving Keyboard Macros | |
1153 | |
1154 @cindex saving keyboard macros | |
1155 @findex name-last-kbd-macro | |
1156 If you wish to save a keyboard macro for longer than until you define the | |
1157 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. | |
1158 This reads a name as an argument using the minibuffer and defines that name | |
1159 to execute the macro. The macro name is a Lisp symbol, and defining it in | |
1160 this way makes it a valid command name for calling with @kbd{M-x} or for | |
1161 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you | |
1162 specify a name that has a prior definition other than another keyboard | |
1163 macro, an error message is printed and nothing is changed. | |
1164 | |
1165 @findex insert-kbd-macro | |
1166 Once a macro has a command name, you can save its definition in a file. | |
1167 Then it can be used in another editing session. First, visit the file | |
1168 you want to save the definition in. Then use this command: | |
1169 | |
1170 @example | |
1171 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} | |
1172 @end example | |
1173 | |
1174 @noindent | |
1175 This inserts some Lisp code that, when executed later, will define the | |
1176 same macro with the same definition it has now. (You need not | |
1177 understand Lisp code to do this, because @code{insert-kbd-macro} writes | |
1178 the Lisp code for you.) Then save the file. You can load the file | |
1179 later with @code{load-file} (@pxref{Lisp Libraries}). If the file you | |
1180 save in is your init file @file{~/.emacs} (@pxref{Init File}) then the | |
1181 macro will be defined each time you run Emacs. | |
1182 | |
1183 If you give @code{insert-kbd-macro} a numeric argument, it makes | |
1184 additional Lisp code to record the keys (if any) that you have bound to the | |
1185 keyboard macro, so that the macro will be reassigned the same keys when you | |
1186 load the file. | |
1187 | |
1188 @node Kbd Macro Query | |
1189 @subsection Executing Macros with Variations | |
1190 | |
1191 @kindex C-x q | |
1192 @findex kbd-macro-query | |
1193 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect | |
1194 similar to that of @code{query-replace}, where the macro asks you each | |
1195 time around whether to make a change. While defining the macro, | |
1196 type @kbd{C-x q} at the point where you want the query to occur. During | |
1197 macro definition, the @kbd{C-x q} does nothing, but when you run the | |
1198 macro later, @kbd{C-x q} asks you interactively whether to continue. | |
1199 | |
1200 The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), | |
1201 @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. | |
1202 The answers are the same as in @code{query-replace}, though not all of | |
1203 the @code{query-replace} options are meaningful. | |
1204 | |
1205 These responses include @key{SPC} to continue, and @key{DEL} to skip | |
1206 the remainder of this repetition of the macro and start right away with | |
1207 the next repetition. @key{RET} means to skip the remainder of this | |
1208 repetition and cancel further repetitions. @kbd{C-l} redraws the screen | |
1209 and asks you again for a character to say what to do. | |
1210 | |
1211 @kbd{C-r} enters a recursive editing level, in which you can perform | |
1212 editing which is not part of the macro. When you exit the recursive | |
1213 edit using @kbd{C-M-c}, you are asked again how to continue with the | |
1214 keyboard macro. If you type a @key{SPC} at this time, the rest of the | |
1215 macro definition is executed. It is up to you to leave point and the | |
1216 text in a state such that the rest of the macro will do what you | |
1217 want.@refill | |
1218 | |
1219 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, | |
1220 performs a completely different function. It enters a recursive edit | |
1221 reading input from the keyboard, both when you type it during the | |
1222 definition of the macro, and when it is executed from the macro. During | |
1223 definition, the editing you do inside the recursive edit does not become | |
1224 part of the macro. During macro execution, the recursive edit gives you | |
1225 a chance to do some particularized editing on each repetition. | |
1226 @xref{Recursive Edit}. | |
1227 | |
1228 Another way to vary the behavior of a keyboard macro is to use a | |
1229 register as a counter, incrementing it on each repetition of the macro. | |
1230 @xref{RegNumbers}. | |
1231 | |
1232 @node Key Bindings | |
1233 @section Customizing Key Bindings | |
1234 @cindex key bindings | |
1235 | |
1236 This section describes @dfn{key bindings}, which map keys to commands, | |
1237 and @dfn{keymaps}, which record key bindings. It also explains how | |
1238 to customize key bindings. | |
1239 | |
1240 Recall that a command is a Lisp function whose definition provides for | |
1241 interactive use. Like every Lisp function, a command has a function | |
1242 name which usually consists of lower-case letters and hyphens. | |
1243 | |
1244 @menu | |
1245 * Keymaps:: Generalities. The global keymap. | |
1246 * Prefix Keymaps:: Keymaps for prefix keys. | |
1247 * Local Keymaps:: Major and minor modes have their own keymaps. | |
1248 * Minibuffer Maps:: The minibuffer uses its own local keymaps. | |
1249 * Rebinding:: How to redefine one key's meaning conveniently. | |
1250 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. | |
1251 * Function Keys:: Rebinding terminal function keys. | |
1252 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. | |
1253 * Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1. | |
1254 * Mouse Buttons:: Rebinding mouse buttons in Emacs. | |
1255 * Disabling:: Disabling a command means confirmation is required | |
1256 before it can be executed. This is done to protect | |
1257 beginners from surprises. | |
1258 @end menu | |
1259 | |
1260 @node Keymaps | |
1261 @subsection Keymaps | |
1262 @cindex keymap | |
1263 | |
1264 The bindings between key sequences and command functions are recorded | |
1265 in data structures called @dfn{keymaps}. Emacs has many of these, each | |
1266 used on particular occasions. | |
1267 | |
1268 Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence | |
1269 of @dfn{input events} that have a meaning as a unit. Input events | |
1270 include characters, function keys and mouse buttons---all the inputs | |
1271 that you can send to the computer with your terminal. A key sequence | |
1272 gets its meaning from its @dfn{binding}, which says what command it | |
1273 runs. The function of keymaps is to record these bindings. | |
1274 | |
1275 @cindex global keymap | |
1276 The @dfn{global} keymap is the most important keymap because it is | |
1277 always in effect. The global keymap defines keys for Fundamental mode; | |
1278 most of these definitions are common to most or all major modes. Each | |
1279 major or minor mode can have its own keymap which overrides the global | |
1280 definitions of some keys. | |
1281 | |
1282 For example, a self-inserting character such as @kbd{g} is | |
1283 self-inserting because the global keymap binds it to the command | |
1284 @code{self-insert-command}. The standard Emacs editing characters such | |
1285 as @kbd{C-a} also get their standard meanings from the global keymap. | |
1286 Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work | |
1287 by storing the new binding in the proper place in the global map. | |
1288 @xref{Rebinding}. | |
1289 | |
1290 Meta characters work differently; Emacs translates each Meta | |
1291 character into a pair of characters starting with @key{ESC}. When you | |
1292 type the character @kbd{M-a} in a key sequence, Emacs replaces it with | |
1293 @kbd{@key{ESC} a}. A meta key comes in as a single input event, but | |
1294 becomes two events for purposes of key bindings. The reason for this is | |
1295 historical, and we might change it someday. | |
1296 | |
1297 @cindex function key | |
1298 Most modern keyboards have function keys as well as character keys. | |
1299 Function keys send input events just as character keys do, and keymaps | |
1300 can have bindings for them. | |
1301 | |
1302 On many terminals, typing a function key actually sends the computer a | |
1303 sequence of characters; the precise details of the sequence depends on | |
1304 which function key and on the model of terminal you are using. (Often | |
1305 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your | |
1306 terminal type properly, it recognizes the character sequences forming | |
1307 function keys wherever they occur in a key sequence (not just at the | |
1308 beginning). Thus, for most purposes, you can pretend the function keys | |
1309 reach Emacs directly and ignore their encoding as character sequences. | |
1310 | |
1311 @cindex mouse | |
1312 Mouse buttons also produce input events. These events come with other | |
1313 data---the window and position where you pressed or released the button, | |
1314 and a time stamp. But only the choice of button matters for key | |
1315 bindings; the other data matters only if a command looks at it. | |
1316 (Commands designed for mouse invocation usually do look at the other | |
1317 data.) | |
1318 | |
1319 A keymap records definitions for single events. Interpreting a key | |
1320 sequence of multiple events involves a chain of keymaps. The first | |
1321 keymap gives a definition for the first event; this definition is | |
1322 another keymap, which is used to look up the second event in the | |
1323 sequence, and so on. | |
1324 | |
1325 Key sequences can mix function keys and characters. For example, | |
1326 @kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix | |
1327 key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse | |
1328 events with keyboard events, but we recommend against it, because such | |
37419
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1329 key sequences are inconvenient to use. |
25829 | 1330 |
37419
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1331 As a user, you can redefine any key; but it is usually best to stick |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1332 to key sequences that consist of @kbd{C-c} followed by a letter. |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1333 These keys are ``reserved for users,'' so they won't conflict with any |
25829 | 1334 properly designed Emacs extension. The function keys @key{F5} through |
1335 @key{F9} are also reserved for users. If you redefine some other key, | |
1336 your definition may be overridden by certain extensions or major modes | |
1337 which redefine the same key. | |
1338 | |
1339 @node Prefix Keymaps | |
1340 @subsection Prefix Keymaps | |
1341 | |
1342 A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap, | |
1343 which holds the definition for the event that immediately follows | |
1344 that prefix. | |
1345 | |
1346 The definition of a prefix key is usually the keymap to use for | |
1347 looking up the following event. The definition can also be a Lisp | |
1348 symbol whose function definition is the following keymap; the effect is | |
1349 the same, but it provides a command name for the prefix key that can be | |
1350 used as a description of what the prefix key is for. Thus, the binding | |
1351 of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function | |
1352 definition is the keymap for @kbd{C-x} commands. The definitions of | |
1353 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in | |
1354 the global map, so these prefix keys are always available. | |
1355 | |
1356 Aside from ordinary prefix keys, there is a fictitious ``prefix key'' | |
1357 which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp | |
1358 Reference Manual}, for special information about menu bar key bindings. | |
1359 Mouse button events that invoke pop-up menus are also prefix keys; see | |
1360 @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more | |
1361 details. | |
1362 | |
1363 Some prefix keymaps are stored in variables with names: | |
1364 | |
1365 @itemize @bullet | |
1366 @item | |
1367 @vindex ctl-x-map | |
1368 @code{ctl-x-map} is the variable name for the map used for characters that | |
1369 follow @kbd{C-x}. | |
1370 @item | |
1371 @vindex help-map | |
1372 @code{help-map} is for characters that follow @kbd{C-h}. | |
1373 @item | |
1374 @vindex esc-map | |
1375 @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta | |
1376 characters are actually defined by this map. | |
1377 @item | |
1378 @vindex ctl-x-4-map | |
1379 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. | |
1380 @item | |
1381 @vindex mode-specific-map | |
1382 @code{mode-specific-map} is for characters that follow @kbd{C-c}. | |
1383 @end itemize | |
1384 | |
1385 @node Local Keymaps | |
1386 @subsection Local Keymaps | |
1387 | |
1388 @cindex local keymap | |
1389 So far we have explained the ins and outs of the global map. Major | |
1390 modes customize Emacs by providing their own key bindings in @dfn{local | |
1391 keymaps}. For example, C mode overrides @key{TAB} to make it indent the | |
1392 current line for C code. Portions of text in the buffer can specify | |
1393 their own keymaps to substitute for the keymap of the buffer's major | |
1394 mode. | |
1395 | |
1396 @cindex minor mode keymap | |
1397 Minor modes can also have local keymaps. Whenever a minor mode is | |
1398 in effect, the definitions in its keymap override both the major | |
1399 mode's local keymap and the global keymap. | |
1400 | |
1401 @vindex c-mode-map | |
1402 @vindex lisp-mode-map | |
1403 The local keymaps for Lisp mode and several other major modes always | |
1404 exist even when not in use. These are kept in variables named | |
1405 @code{lisp-mode-map} and so on. For major modes less often used, the | |
1406 local keymap is normally constructed only when the mode is used for the | |
1407 first time in a session. This is to save space. If you wish to change | |
1408 one of these keymaps, you must use the major mode's @dfn{mode | |
1409 hook}---see below. | |
1410 | |
1411 All minor mode keymaps are created in advance. There is no way to | |
1412 defer their creation until the first time the minor mode is enabled. | |
1413 | |
1414 A local keymap can locally redefine a key as a prefix key by defining | |
1415 it as a prefix keymap. If the key is also defined globally as a prefix, | |
1416 then its local and global definitions (both keymaps) effectively | |
1417 combine: both of them are used to look up the event that follows the | |
1418 prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as | |
1419 another keymap, and that keymap defines @kbd{C-z} as a command, this | |
1420 provides a local meaning for @kbd{C-c C-z}. This does not affect other | |
1421 sequences that start with @kbd{C-c}; if those sequences don't have their | |
1422 own local bindings, their global bindings remain in effect. | |
1423 | |
1424 Another way to think of this is that Emacs handles a multi-event key | |
1425 sequence by looking in several keymaps, one by one, for a binding of the | |
1426 whole key sequence. First it checks the minor mode keymaps for minor | |
1427 modes that are enabled, then it checks the major mode's keymap, and then | |
1428 it checks the global keymap. This is not precisely how key lookup | |
1429 works, but it's good enough for understanding ordinary circumstances. | |
1430 | |
1431 @cindex rebinding major mode keys | |
26392
b3d3ff9a7a2c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25829
diff
changeset
|
1432 @findex define-key |
25829 | 1433 To change the local bindings of a major mode, you must change the |
1434 mode's local keymap. Normally you must wait until the first time the | |
1435 mode is used, because most major modes don't create their keymaps until | |
1436 then. If you want to specify something in your @file{~/.emacs} file to | |
1437 change a major mode's bindings, you must use the mode's mode hook to | |
1438 delay the change until the mode is first used. | |
1439 | |
1440 For example, the command @code{texinfo-mode} to select Texinfo mode | |
1441 runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook | |
1442 to add local bindings (not very useful, we admit) for @kbd{C-c n} and | |
1443 @kbd{C-c p} in Texinfo mode: | |
1444 | |
1445 @example | |
1446 (add-hook 'texinfo-mode-hook | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1447 '(lambda () |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1448 (define-key texinfo-mode-map "\C-cp" |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1449 'backward-paragraph) |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1450 (define-key texinfo-mode-map "\C-cn" |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1451 'forward-paragraph))) |
25829 | 1452 @end example |
1453 | |
1454 @xref{Hooks}. | |
1455 | |
1456 @node Minibuffer Maps | |
1457 @subsection Minibuffer Keymaps | |
1458 | |
1459 @cindex minibuffer keymaps | |
1460 @vindex minibuffer-local-map | |
1461 @vindex minibuffer-local-ns-map | |
1462 @vindex minibuffer-local-completion-map | |
1463 @vindex minibuffer-local-must-match-map | |
1464 The minibuffer has its own set of local keymaps; they contain various | |
1465 completion and exit commands. | |
1466 | |
1467 @itemize @bullet | |
1468 @item | |
1469 @code{minibuffer-local-map} is used for ordinary input (no completion). | |
1470 @item | |
1471 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits | |
1472 just like @key{RET}. This is used mainly for Mocklisp compatibility. | |
1473 @item | |
1474 @code{minibuffer-local-completion-map} is for permissive completion. | |
1475 @item | |
1476 @code{minibuffer-local-must-match-map} is for strict completion and | |
1477 for cautious completion. | |
1478 @end itemize | |
1479 | |
1480 @node Rebinding | |
1481 @subsection Changing Key Bindings Interactively | |
1482 @cindex key rebinding, this session | |
36263
11db0318031d
Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents:
36148
diff
changeset
|
1483 @cindex redefining keys, this session |
25829 | 1484 |
1485 The way to redefine an Emacs key is to change its entry in a keymap. | |
1486 You can change the global keymap, in which case the change is effective in | |
1487 all major modes (except those that have their own overriding local | |
1488 definitions for the same key). Or you can change the current buffer's | |
1489 local map, which affects all buffers using the same major mode. | |
1490 | |
1491 @findex global-set-key | |
1492 @findex local-set-key | |
1493 @findex global-unset-key | |
1494 @findex local-unset-key | |
1495 @table @kbd | |
1496 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} | |
1497 Define @var{key} globally to run @var{cmd}. | |
1498 @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} | |
1499 Define @var{key} locally (in the major mode now in effect) to run | |
1500 @var{cmd}. | |
1501 @item M-x global-unset-key @key{RET} @var{key} | |
1502 Make @var{key} undefined in the global map. | |
1503 @item M-x local-unset-key @key{RET} @var{key} | |
1504 Make @var{key} undefined locally (in the major mode now in effect). | |
1505 @end table | |
1506 | |
1507 For example, suppose you like to execute commands in a subshell within | |
1508 an Emacs buffer, instead of suspending Emacs and executing commands in | |
1509 your login shell. Normally, @kbd{C-z} is bound to the function | |
1510 @code{suspend-emacs} (when not using the X Window System), but you can | |
1511 change @kbd{C-z} to invoke an interactive subshell within Emacs, by | |
1512 binding it to @code{shell} as follows: | |
1513 | |
1514 @example | |
1515 M-x global-set-key @key{RET} C-z shell @key{RET} | |
1516 @end example | |
1517 | |
1518 @noindent | |
1519 @code{global-set-key} reads the command name after the key. After you | |
1520 press the key, a message like this appears so that you can confirm that | |
1521 you are binding the key you want: | |
1522 | |
1523 @example | |
1524 Set key C-z to command: | |
1525 @end example | |
1526 | |
1527 You can redefine function keys and mouse events in the same way; just | |
1528 type the function key or click the mouse when it's time to specify the | |
1529 key to rebind. | |
1530 | |
1531 You can rebind a key that contains more than one event in the same | |
1532 way. Emacs keeps reading the key to rebind until it is a complete key | |
1533 (that is, not a prefix key). Thus, if you type @kbd{C-f} for | |
1534 @var{key}, that's the end; the minibuffer is entered immediately to | |
1535 read @var{cmd}. But if you type @kbd{C-x}, another character is read; | |
1536 if that is @kbd{4}, another character is read, and so on. For | |
1537 example, | |
1538 | |
1539 @example | |
1540 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} | |
1541 @end example | |
1542 | |
1543 @noindent | |
1544 redefines @kbd{C-x 4 $} to run the (fictitious) command | |
1545 @code{spell-other-window}. | |
1546 | |
1547 The two-character keys consisting of @kbd{C-c} followed by a letter | |
1548 are reserved for user customizations. Lisp programs are not supposed to | |
1549 define these keys, so the bindings you make for them will be available | |
1550 in all major modes and will never get in the way of anything. | |
1551 | |
1552 You can remove the global definition of a key with | |
1553 @code{global-unset-key}. This makes the key @dfn{undefined}; if you | |
1554 type it, Emacs will just beep. Similarly, @code{local-unset-key} makes | |
1555 a key undefined in the current major mode keymap, which makes the global | |
1556 definition (or lack of one) come back into effect in that major mode. | |
1557 | |
1558 If you have redefined (or undefined) a key and you subsequently wish | |
1559 to retract the change, undefining the key will not do the job---you need | |
1560 to redefine the key with its standard definition. To find the name of | |
1561 the standard definition of a key, go to a Fundamental mode buffer and | |
1562 use @kbd{C-h c}. The documentation of keys in this manual also lists | |
1563 their command names. | |
1564 | |
1565 If you want to prevent yourself from invoking a command by mistake, it | |
1566 is better to disable the command than to undefine the key. A disabled | |
1567 command is less work to invoke when you really want to. | |
1568 @xref{Disabling}. | |
1569 | |
1570 @node Init Rebinding | |
1571 @subsection Rebinding Keys in Your Init File | |
1572 | |
1573 If you have a set of key bindings that you like to use all the time, | |
1574 you can specify them in your @file{.emacs} file by using their Lisp | |
26392
b3d3ff9a7a2c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25829
diff
changeset
|
1575 syntax. (@xref{Init File}.) |
25829 | 1576 |
1577 The simplest method for doing this works for ASCII characters and | |
1578 Meta-modified ASCII characters only. This method uses a string to | |
1579 represent the key sequence you want to rebind. For example, here's how | |
1580 to bind @kbd{C-z} to @code{shell}: | |
1581 | |
1582 @example | |
1583 (global-set-key "\C-z" 'shell) | |
1584 @end example | |
1585 | |
1586 @noindent | |
1587 This example uses a string constant containing one character, @kbd{C-z}. | |
1588 The single-quote before the command name, @code{shell}, marks it as a | |
1589 constant symbol rather than a variable. If you omit the quote, Emacs | |
1590 would try to evaluate @code{shell} immediately as a variable. This | |
1591 probably causes an error; it certainly isn't what you want. | |
1592 | |
1593 Here is another example that binds a key sequence two characters long: | |
1594 | |
1595 @example | |
1596 (global-set-key "\C-xl" 'make-symbolic-link) | |
1597 @end example | |
1598 | |
37419
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1599 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1600 string, you can use the Emacs Lisp escape sequences, @samp{\t}, |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1601 @samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1602 @kbd{C-x @key{TAB}}: |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1603 |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1604 @example |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1605 (global-set-key "\C-x\t" 'indent-rigidly) |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1606 @end example |
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1607 |
25829 | 1608 When the key sequence includes function keys or mouse button events, |
1609 or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use | |
1610 the more general method of rebinding, which uses a vector to specify the | |
1611 key sequence. | |
1612 | |
1613 The way to write a vector in Emacs Lisp is with square brackets around | |
1614 the vector elements. Use spaces to separate the elements. If an | |
1615 element is a symbol, simply write the symbol's name---no other | |
1616 delimiters or punctuation are needed. If a vector element is a | |
1617 character, write it as a Lisp character constant: @samp{?} followed by | |
1618 the character as it would appear in a string. | |
1619 | |
1620 Here are examples of using vectors to rebind @kbd{C-=} (a control | |
38114 | 1621 character not in ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't |
25829 | 1622 have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a |
1623 keyboard-modified mouse button): | |
1624 | |
1625 @example | |
1626 (global-set-key [?\C-=] 'make-symbolic-link) | |
1627 (global-set-key [?\H-a] 'make-symbolic-link) | |
1628 (global-set-key [f7] 'make-symbolic-link) | |
1629 (global-set-key [C-mouse-1] 'make-symbolic-link) | |
1630 @end example | |
1631 | |
1632 You can use a vector for the simple cases too. Here's how to rewrite | |
37419
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1633 the first three examples, above, using vectors: |
25829 | 1634 |
1635 @example | |
1636 (global-set-key [?\C-z] 'shell) | |
1637 (global-set-key [?\C-x ?l] 'make-symbolic-link) | |
37419
201fa171a6e2
Explain binding TAB etc using \t etc.
Richard M. Stallman <rms@gnu.org>
parents:
37354
diff
changeset
|
1638 (global-set-key [?\C-x ?\t] 'indent-rigidly) |
25829 | 1639 @end example |
1640 | |
1641 @node Function Keys | |
1642 @subsection Rebinding Function Keys | |
1643 | |
1644 Key sequences can contain function keys as well as ordinary | |
1645 characters. Just as Lisp characters (actually integers) represent | |
1646 keyboard characters, Lisp symbols represent function keys. If the | |
1647 function key has a word as its label, then that word is also the name of | |
1648 the corresponding Lisp symbol. Here are the conventional Lisp names for | |
1649 common function keys: | |
1650 | |
1651 @table @asis | |
1652 @item @code{left}, @code{up}, @code{right}, @code{down} | |
1653 Cursor arrow keys. | |
1654 | |
1655 @item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} | |
1656 Other cursor repositioning keys. | |
1657 | |
1658 @item @code{select}, @code{print}, @code{execute}, @code{backtab} | |
1659 @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
1660 @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} |
25829 | 1661 Miscellaneous function keys. |
1662 | |
1663 @item @code{f1}, @code{f2}, @dots{} @code{f35} | |
1664 Numbered function keys (across the top of the keyboard). | |
1665 | |
1666 @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} | |
1667 @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} | |
1668 @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} | |
1669 Keypad keys (to the right of the regular keyboard), with names or punctuation. | |
1670 | |
1671 @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} | |
1672 Keypad keys with digits. | |
1673 | |
1674 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} | |
1675 Keypad PF keys. | |
1676 @end table | |
1677 | |
1678 These names are conventional, but some systems (especially when using | |
35188
94d46968a93f
Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents:
34151
diff
changeset
|
1679 X) may use different names. To make certain what symbol is used for a |
94d46968a93f
Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents:
34151
diff
changeset
|
1680 given function key on your terminal, type @kbd{C-h c} followed by that |
94d46968a93f
Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents:
34151
diff
changeset
|
1681 key. |
25829 | 1682 |
1683 A key sequence which contains function key symbols (or anything but | |
1684 ASCII characters) must be a vector rather than a string. The vector | |
1685 syntax uses spaces between the elements, and square brackets around the | |
1686 whole vector. Thus, to bind function key @samp{f1} to the command | |
1687 @code{rmail}, write the following: | |
1688 | |
1689 @example | |
1690 (global-set-key [f1] 'rmail) | |
1691 @end example | |
1692 | |
1693 @noindent | |
1694 To bind the right-arrow key to the command @code{forward-char}, you can | |
1695 use this expression: | |
1696 | |
1697 @example | |
1698 (global-set-key [right] 'forward-char) | |
1699 @end example | |
1700 | |
1701 @noindent | |
1702 This uses the Lisp syntax for a vector containing the symbol | |
1703 @code{right}. (This binding is present in Emacs by default.) | |
1704 | |
1705 @xref{Init Rebinding}, for more information about using vectors for | |
1706 rebinding. | |
1707 | |
1708 You can mix function keys and characters in a key sequence. This | |
1709 example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}. | |
1710 | |
1711 @example | |
1712 (global-set-key [?\C-x next] 'forward-page) | |
1713 @end example | |
1714 | |
1715 @noindent | |
1716 where @code{?\C-x} is the Lisp character constant for the character | |
1717 @kbd{C-x}. The vector element @code{next} is a symbol and therefore | |
1718 does not take a question mark. | |
1719 | |
1720 You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER}, | |
1721 @key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent | |
1722 these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-}, | |
1723 @samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name. | |
1724 Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a | |
1725 word: | |
1726 | |
1727 @example | |
1728 (global-set-key [H-M-right] 'forward-word) | |
1729 @end example | |
1730 | |
1731 @node Named ASCII Chars | |
1732 @subsection Named ASCII Control Characters | |
1733 | |
1734 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} | |
1735 started out as names for certain ASCII control characters, used so often | |
1736 that they have special keys of their own. Later, users found it | |
1737 convenient to distinguish in Emacs between these keys and the ``same'' | |
1738 control characters typed with the @key{CTRL} key. | |
1739 | |
36656
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1740 Emacs distinguishes these two kinds of input, when the keyboard |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1741 reports these keys to Emacs. It treats the ``special'' keys as function |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1742 keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed}, |
25829 | 1743 @code{escape}, and @code{delete}. These function keys translate |
1744 automatically into the corresponding ASCII characters @emph{if} they | |
1745 have no bindings of their own. As a result, neither users nor Lisp | |
1746 programs need to pay attention to the distinction unless they care to. | |
1747 | |
1748 If you do not want to distinguish between (for example) @key{TAB} and | |
1749 @kbd{C-i}, make just one binding, for the ASCII character @key{TAB} | |
1750 (octal code 011). If you do want to distinguish, make one binding for | |
1751 this ASCII character, and another for the ``function key'' @code{tab}. | |
1752 | |
1753 With an ordinary ASCII terminal, there is no way to distinguish | |
1754 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), | |
1755 because the terminal sends the same character in both cases. | |
1756 | |
1757 @node Non-ASCII Rebinding | |
1758 @subsection Non-ASCII Characters on the Keyboard | |
1759 | |
1760 If your keyboard has keys that send non-ASCII characters, such as | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1761 accented letters, rebinding these keys is a bit tricky. There are two |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1762 solutions you can use. One is to specify a keyboard coding system, |
25829 | 1763 using @code{set-keyboard-coding-system} (@pxref{Specify Coding}). |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1764 Then you can bind these keys in the usual way@footnote{Note that you |
27218 | 1765 should avoid the string syntax for binding 8-bit characters, since |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1766 they will be interpreted as meta keys. @xref{Strings of |
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
1767 Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this: |
25829 | 1768 |
1769 @example | |
1770 (global-set-key [?@var{char}] 'some-function) | |
1771 @end example | |
1772 | |
1773 @noindent | |
36632
1bfc2fad762a
(File Variables): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents:
36593
diff
changeset
|
1774 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}. |
25829 | 1775 |
1776 If you don't specify the keyboard coding system, that approach won't | |
1777 work. Instead, you need to find out the actual code that the terminal | |
1778 sends. The easiest way to do this in Emacs is to create an empty buffer | |
1779 with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x | |
1780 toggle-enable-multibyte-characters @key{RET}}, then type the key to | |
1781 insert the character into this buffer. | |
1782 | |
1783 Move point before the character, then type @kbd{C-x =}. This | |
1784 displays a message in the minibuffer, showing the character code in | |
1785 three ways, octal, decimal and hexadecimal, all within a set of | |
1786 parentheses. Use the second of the three numbers, the decimal one, | |
1787 inside the vector to bind: | |
1788 | |
1789 @example | |
1790 (global-set-key [@var{decimal-code}] 'some-function) | |
1791 @end example | |
1792 | |
27218 | 1793 If you bind 8-bit characters like this in your init file, you my find it |
1794 convenient to specify that it is unibyte. @xref{Enabling Multibyte}. | |
1795 | |
25829 | 1796 @node Mouse Buttons |
1797 @subsection Rebinding Mouse Buttons | |
1798 @cindex mouse button events | |
1799 @cindex rebinding mouse buttons | |
1800 @cindex click events | |
1801 @cindex drag events | |
1802 @cindex down events | |
1803 @cindex button down events | |
1804 | |
1805 Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary | |
1806 mouse events in Emacs are @dfn{click} events; these happen when you | |
1807 press a button and release it without moving the mouse. You can also | |
1808 get @dfn{drag} events, when you move the mouse while holding the button | |
1809 down. Drag events happen when you finally let go of the button. | |
1810 | |
1811 The symbols for basic click events are @code{mouse-1} for the leftmost | |
1812 button, @code{mouse-2} for the next, and so on. Here is how you can | |
1813 redefine the second mouse button to split the current window: | |
1814 | |
1815 @example | |
1816 (global-set-key [mouse-2] 'split-window-vertically) | |
1817 @end example | |
1818 | |
1819 The symbols for drag events are similar, but have the prefix | |
1820 @samp{drag-} before the word @samp{mouse}. For example, dragging the | |
1821 first button generates a @code{drag-mouse-1} event. | |
1822 | |
1823 You can also define bindings for events that occur when a mouse button | |
1824 is pressed down. These events start with @samp{down-} instead of | |
1825 @samp{drag-}. Such events are generated only if they have key bindings. | |
1826 When you get a button-down event, a corresponding click or drag event | |
1827 will always follow. | |
1828 | |
1829 @cindex double clicks | |
1830 @cindex triple clicks | |
1831 If you wish, you can distinguish single, double, and triple clicks. A | |
1832 double click means clicking a mouse button twice in approximately the | |
1833 same place. The first click generates an ordinary click event. The | |
1834 second click, if it comes soon enough, generates a double-click event | |
1835 instead. The event type for a double-click event starts with | |
1836 @samp{double-}: for example, @code{double-mouse-3}. | |
1837 | |
1838 This means that you can give a special meaning to the second click at | |
1839 the same place, but it must act on the assumption that the ordinary | |
1840 single click definition has run when the first click was received. | |
1841 | |
1842 This constrains what you can do with double clicks, but user interface | |
1843 designers say that this constraint ought to be followed in any case. A | |
1844 double click should do something similar to the single click, only | |
1845 ``more so.'' The command for the double-click event should perform the | |
1846 extra work for the double click. | |
1847 | |
1848 If a double-click event has no binding, it changes to the | |
1849 corresponding single-click event. Thus, if you don't define a | |
1850 particular double click specially, it executes the single-click command | |
1851 twice. | |
1852 | |
1853 Emacs also supports triple-click events whose names start with | |
1854 @samp{triple-}. Emacs does not distinguish quadruple clicks as event | |
1855 types; clicks beyond the third generate additional triple-click events. | |
1856 However, the full number of clicks is recorded in the event list, so you | |
1857 can distinguish if you really want to. We don't recommend distinct | |
1858 meanings for more than three clicks, but sometimes it is useful for | |
1859 subsequent clicks to cycle through the same set of three meanings, so | |
1860 that four clicks are equivalent to one click, five are equivalent to | |
1861 two, and six are equivalent to three. | |
1862 | |
1863 Emacs also records multiple presses in drag and button-down events. | |
1864 For example, when you press a button twice, then move the mouse while | |
1865 holding the button, Emacs gets a @samp{double-drag-} event. And at the | |
1866 moment when you press it down for the second time, Emacs gets a | |
1867 @samp{double-down-} event (which is ignored, like all button-down | |
1868 events, if it has no binding). | |
1869 | |
1870 @vindex double-click-time | |
1871 The variable @code{double-click-time} specifies how long may elapse | |
1872 between clicks that are recognized as a pair. Its value is measured | |
1873 in milliseconds. If the value is @code{nil}, double clicks are not | |
1874 detected at all. If the value is @code{t}, then there is no time | |
1875 limit. | |
1876 | |
1877 The symbols for mouse events also indicate the status of the modifier | |
1878 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, | |
1879 @samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} | |
1880 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. | |
1881 | |
1882 A frame includes areas that don't show text from the buffer, such as | |
1883 the mode line and the scroll bar. You can tell whether a mouse button | |
1884 comes from a special area of the screen by means of dummy ``prefix | |
1885 keys.'' For example, if you click the mouse in the mode line, you get | |
1886 the prefix key @code{mode-line} before the ordinary mouse-button symbol. | |
1887 Thus, here is how to define the command for clicking the first button in | |
1888 a mode line to run @code{scroll-up}: | |
1889 | |
1890 @example | |
1891 (global-set-key [mode-line mouse-1] 'scroll-up) | |
1892 @end example | |
1893 | |
1894 Here is the complete list of these dummy prefix keys and their | |
1895 meanings: | |
1896 | |
1897 @table @code | |
1898 @item mode-line | |
1899 The mouse was in the mode line of a window. | |
1900 @item vertical-line | |
1901 The mouse was in the vertical line separating side-by-side windows. (If | |
1902 you use scroll bars, they appear in place of these vertical lines.) | |
1903 @item vertical-scroll-bar | |
1904 The mouse was in a vertical scroll bar. (This is the only kind of | |
1905 scroll bar Emacs currently supports.) | |
1906 @ignore | |
1907 @item horizontal-scroll-bar | |
1908 The mouse was in a horizontal scroll bar. Horizontal scroll bars do | |
1909 horizontal scrolling, and people don't use them often. | |
1910 @end ignore | |
1911 @end table | |
1912 | |
1913 You can put more than one mouse button in a key sequence, but it isn't | |
1914 usual to do so. | |
1915 | |
1916 @node Disabling | |
1917 @subsection Disabling Commands | |
1918 @cindex disabled command | |
1919 | |
1920 Disabling a command marks the command as requiring confirmation before it | |
1921 can be executed. The purpose of disabling a command is to prevent | |
1922 beginning users from executing it by accident and being confused. | |
1923 | |
1924 An attempt to invoke a disabled command interactively in Emacs | |
1925 displays a window containing the command's name, its documentation, and | |
1926 some instructions on what to do immediately; then Emacs asks for input | |
1927 saying whether to execute the command as requested, enable it and | |
1928 execute it, or cancel. If you decide to enable the command, you are | |
1929 asked whether to do this permanently or just for the current session. | |
37977
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
1930 (Enabling permanently works by automatically editing your @file{.emacs} |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
1931 file.) You can also type @kbd{!} to enable @emph{all} commands, |
5ff6cac52888
Update Customization buffer examples
Richard M. Stallman <rms@gnu.org>
parents:
37976
diff
changeset
|
1932 for the current session only. |
25829 | 1933 |
1934 The direct mechanism for disabling a command is to put a | |
1935 non-@code{nil} @code{disabled} property on the Lisp symbol for the | |
1936 command. Here is the Lisp program to do this: | |
1937 | |
1938 @example | |
1939 (put 'delete-region 'disabled t) | |
1940 @end example | |
1941 | |
1942 If the value of the @code{disabled} property is a string, that string | |
1943 is included in the message printed when the command is used: | |
1944 | |
1945 @example | |
1946 (put 'delete-region 'disabled | |
1947 "It's better to use `kill-region' instead.\n") | |
1948 @end example | |
1949 | |
1950 @findex disable-command | |
1951 @findex enable-command | |
1952 You can make a command disabled either by editing the @file{.emacs} | |
1953 file directly or with the command @kbd{M-x disable-command}, which edits | |
1954 the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} | |
1955 edits @file{.emacs} to enable a command permanently. @xref{Init File}. | |
1956 | |
1957 Whether a command is disabled is independent of what key is used to | |
1958 invoke it; disabling also applies if the command is invoked using | |
1959 @kbd{M-x}. Disabling a command has no effect on calling it as a | |
1960 function from Lisp programs. | |
1961 | |
1962 @node Keyboard Translations | |
1963 @section Keyboard Translations | |
1964 | |
1965 Some keyboards do not make it convenient to send all the special | |
1966 characters that Emacs uses. The most common problem case is the | |
1967 @key{DEL} character. Some keyboards provide no convenient way to type | |
1968 this very important character---usually because they were designed to | |
1969 expect the character @kbd{C-h} to be used for deletion. On these | |
1970 keyboards, if you press the key normally used for deletion, Emacs handles | |
1971 the @kbd{C-h} as a prefix character and offers you a list of help | |
1972 options, which is not what you want. | |
1973 | |
1974 @cindex keyboard translations | |
1975 @findex keyboard-translate | |
1976 You can work around this problem within Emacs by setting up keyboard | |
1977 translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into | |
1978 @kbd{C-h}, as follows: | |
1979 | |
1980 @example | |
1981 ;; @r{Translate @kbd{C-h} to @key{DEL}.} | |
1982 (keyboard-translate ?\C-h ?\C-?) | |
1983 | |
1984 ;; @r{Translate @key{DEL} to @kbd{C-h}.} | |
1985 (keyboard-translate ?\C-? ?\C-h) | |
1986 @end example | |
1987 | |
1988 Keyboard translations are not the same as key bindings in keymaps | |
1989 (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in | |
1990 different situations, but there is only one set of keyboard | |
1991 translations, and it applies to every character that Emacs reads from | |
1992 the terminal. Keyboard translations take place at the lowest level of | |
1993 input processing; the keys that are looked up in keymaps contain the | |
1994 characters that result from keyboard translation. | |
1995 | |
36656
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1996 On a window system, the keyboard key named @key{DELETE} is a function |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1997 key and is distinct from the ASCII character named @key{DEL}. |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1998 @xref{Named ASCII Chars}. Keyboard translations affect only ASCII |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
1999 character input, not function keys; thus, the above example used on a |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
2000 window system does not affect the @key{DELETE} key. However, the |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
2001 translation above isn't necessary on window systems, because Emacs can |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
2002 also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it |
e562b27b8afd
DELETE and BACSKPACE are supported on any window system, not only X.
Eli Zaretskii <eliz@gnu.org>
parents:
36632
diff
changeset
|
2003 normally treats @key{BACKSPACE} as @key{DEL}. |
25829 | 2004 |
2005 For full information about how to use keyboard translations, see | |
2006 @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}. | |
2007 | |
2008 @node Syntax | |
2009 @section The Syntax Table | |
2010 @cindex syntax table | |
2011 | |
2012 All the Emacs commands which parse words or balance parentheses are | |
2013 controlled by the @dfn{syntax table}. The syntax table says which | |
2014 characters are opening delimiters, which are parts of words, which are | |
37122
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2015 string quotes, and so on. It does this by assigning each character to |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2016 one of fifteen-odd @dfn{syntax classes}. In some cases it specifies |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2017 some additional information also. |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2018 |
38114 | 2019 Each major mode has its own syntax table (though related major modes |
2020 sometimes share one syntax table) which it installs in each buffer | |
37122
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2021 that uses the mode. The syntax table installed in the current buffer |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2022 is the one that all commands use, so we call it ``the'' syntax table. |
25829 | 2023 |
2024 @kindex C-h s | |
2025 @findex describe-syntax | |
37122
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2026 To display a description of the contents of the current syntax |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2027 table, type @kbd{C-h s} (@code{describe-syntax}). The description of |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2028 each character includes both the string you would have to give to |
25829 | 2029 @code{modify-syntax-entry} to set up that character's current syntax, |
37122
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2030 starting with the character which designates its syntax class, plus |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2031 some English text to explain its meaning. |
25829 | 2032 |
37122
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2033 A syntax table is actually a Lisp object, a char-table, whose |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2034 elements are cons cells. For full information on the syntax table, |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2035 see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp |
a34d1e2a580f
Correct syntax table data structure. Other clarifications about
Richard M. Stallman <rms@gnu.org>
parents:
36656
diff
changeset
|
2036 Reference Manual}. |
25829 | 2037 |
2038 @node Init File | |
2039 @section The Init File, @file{~/.emacs} | |
2040 @cindex init file | |
2041 @cindex Emacs initialization file | |
2042 @cindex key rebinding, permanent | |
2043 @cindex rebinding keys, permanently | |
2044 @cindex startup (init file) | |
2045 | |
2046 When Emacs is started, it normally loads a Lisp program from the file | |
2047 @file{.emacs} or @file{.emacs.el} in your home directory. We call this | |
2048 file your @dfn{init file} because it specifies how to initialize Emacs | |
2049 for you. You can use the command line switch @samp{-q} to prevent | |
2050 loading your init file, and @samp{-u} (or @samp{--user}) to specify a | |
2051 different user's init file (@pxref{Entering Emacs}). | |
2052 | |
37596
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2053 @cindex @file{default.el}, the default init file |
25829 | 2054 There can also be a @dfn{default init file}, which is the library |
2055 named @file{default.el}, found via the standard search path for | |
2056 libraries. The Emacs distribution contains no such library; your site | |
2057 may create one for local customizations. If this library exists, it is | |
2058 loaded whenever you start Emacs (except when you specify @samp{-q}). | |
2059 But your init file, if any, is loaded first; if it sets | |
2060 @code{inhibit-default-init} non-@code{nil}, then @file{default} is not | |
2061 loaded. | |
2062 | |
37596
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2063 @cindex site init file |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2064 @cindex @file{site-start.el}, the site startup file |
25829 | 2065 Your site may also have a @dfn{site startup file}; this is named |
37596
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2066 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2067 finds this file via the standard search path for Lisp libraries. |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2068 Emacs loads this library before it loads your init file. To inhibit |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2069 loading of this library, use the option @samp{-no-site-file}. |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2070 @xref{Initial Options}. |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2071 |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2072 You can place @file{default.el} and @file{site-start.el} in any of |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2073 the directories which Emacs searches for Lisp libraries. The variable |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2074 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories. |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2075 Many sites put these files in the @file{site-lisp} subdirectory of the |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2076 Emacs installation directory, typically |
47f8d088e385
(Init File): Say explicitly that site-start.el is also searched along
Eli Zaretskii <eliz@gnu.org>
parents:
37581
diff
changeset
|
2077 @file{/usr/local/share/emacs/site-lisp}. |
25829 | 2078 |
2079 If you have a large amount of code in your @file{.emacs} file, you | |
2080 should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte | |
2081 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}, | |
2082 for more information about compiling Emacs Lisp programs. | |
2083 | |
2084 If you are going to write actual Emacs Lisp programs that go beyond | |
2085 minor customization, you should read the @cite{Emacs Lisp Reference Manual}. | |
2086 @ifinfo | |
2087 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference | |
2088 Manual}. | |
2089 @end ifinfo | |
2090 | |
2091 @menu | |
2092 * Init Syntax:: Syntax of constants in Emacs Lisp. | |
2093 * Init Examples:: How to do some things with an init file. | |
2094 * Terminal Init:: Each terminal type can have an init file. | |
2095 * Find Init:: How Emacs finds the init file. | |
2096 @end menu | |
2097 | |
2098 @node Init Syntax | |
2099 @subsection Init File Syntax | |
2100 | |
2101 The @file{.emacs} file contains one or more Lisp function call | |
2102 expressions. Each of these consists of a function name followed by | |
2103 arguments, all surrounded by parentheses. For example, @code{(setq | |
2104 fill-column 60)} calls the function @code{setq} to set the variable | |
2105 @code{fill-column} (@pxref{Filling}) to 60. | |
2106 | |
2107 The second argument to @code{setq} is an expression for the new value of | |
2108 the variable. This can be a constant, a variable, or a function call | |
2109 expression. In @file{.emacs}, constants are used most of the time. They can be: | |
2110 | |
2111 @table @asis | |
2112 @item Numbers: | |
2113 Numbers are written in decimal, with an optional initial minus sign. | |
2114 | |
2115 @item Strings: | |
2116 @cindex Lisp string syntax | |
2117 @cindex string syntax | |
2118 Lisp string syntax is the same as C string syntax with a few extra | |
2119 features. Use a double-quote character to begin and end a string constant. | |
2120 | |
2121 In a string, you can include newlines and special characters literally. | |
2122 But often it is cleaner to use backslash sequences for them: @samp{\n} | |
2123 for newline, @samp{\b} for backspace, @samp{\r} for carriage return, | |
2124 @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for | |
2125 escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or | |
2126 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}. | |
2127 Backslash and double-quote are the only characters for which backslash | |
2128 sequences are mandatory. | |
2129 | |
2130 @samp{\C-} can be used as a prefix for a control character, as in | |
2131 @samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for | |
2132 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for | |
2133 @kbd{Control-Meta-A}.@refill | |
2134 | |
37198
12c496043cb0
(Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents:
37122
diff
changeset
|
2135 @cindex international characters in @file{.emacs} |
12c496043cb0
(Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents:
37122
diff
changeset
|
2136 @cindex non-ASCII characters in @file{.emacs} |
12c496043cb0
(Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents:
37122
diff
changeset
|
2137 If you want to include non-ASCII characters in strings in your init |
37354
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2138 file, you should consider putting a @w{@samp{-*-coding: |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2139 @var{coding-system}-*-}} tag on the first line which states the coding |
37265
d2c4a8eb274a
(Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
37198
diff
changeset
|
2140 system used to save your @file{.emacs}, as explained in @ref{Recognize |
d2c4a8eb274a
(Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
37198
diff
changeset
|
2141 Coding}. This is because the defaults for decoding non-ASCII text might |
d2c4a8eb274a
(Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
37198
diff
changeset
|
2142 not yet be set up by the time Emacs reads those parts of your init file |
d2c4a8eb274a
(Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
37198
diff
changeset
|
2143 which use such strings, possibly leading Emacs to decode those strings |
d2c4a8eb274a
(Init Syntax): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
37198
diff
changeset
|
2144 incorrectly. |
37198
12c496043cb0
(Init Syntax): Mention the -*-coding:-*- tag if .emacs uses non-ASCII
Eli Zaretskii <eliz@gnu.org>
parents:
37122
diff
changeset
|
2145 |
25829 | 2146 @item Characters: |
2147 Lisp character constant syntax consists of a @samp{?} followed by | |
2148 either a character or an escape sequence starting with @samp{\}. | |
2149 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that | |
2150 strings and characters are not interchangeable in Lisp; some contexts | |
2151 require one and some contexts require the other. | |
2152 | |
37354
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2153 @xref{Non-ASCII Rebinding}, for information about binding commands to |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2154 keys which send non-ASCII characters. |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2155 |
25829 | 2156 @item True: |
2157 @code{t} stands for `true'. | |
2158 | |
2159 @item False: | |
2160 @code{nil} stands for `false'. | |
2161 | |
2162 @item Other Lisp objects: | |
37976
23dc2eca0bd3
Proofreading changes from Tim Goodwin <tjg@star.le.ac.uk>.
Eli Zaretskii <eliz@gnu.org>
parents:
37843
diff
changeset
|
2163 Write a single-quote (@code{'}) followed by the Lisp object you want. |
25829 | 2164 @end table |
2165 | |
2166 @node Init Examples | |
2167 @subsection Init File Examples | |
2168 | |
2169 Here are some examples of doing certain commonly desired things with | |
2170 Lisp expressions: | |
2171 | |
2172 @itemize @bullet | |
2173 @item | |
2174 Make @key{TAB} in C mode just insert a tab if point is in the middle of a | |
2175 line. | |
2176 | |
2177 @example | |
2178 (setq c-tab-always-indent nil) | |
2179 @end example | |
2180 | |
2181 Here we have a variable whose value is normally @code{t} for `true' | |
2182 and the alternative is @code{nil} for `false'. | |
2183 | |
2184 @item | |
2185 Make searches case sensitive by default (in all buffers that do not | |
2186 override this). | |
2187 | |
2188 @example | |
2189 (setq-default case-fold-search nil) | |
2190 @end example | |
2191 | |
2192 This sets the default value, which is effective in all buffers that do | |
2193 not have local values for the variable. Setting @code{case-fold-search} | |
2194 with @code{setq} affects only the current buffer's local value, which | |
2195 is not what you probably want to do in an init file. | |
2196 | |
2197 @item | |
2198 @vindex user-mail-address | |
2199 Specify your own email address, if Emacs can't figure it out correctly. | |
2200 | |
2201 @example | |
2202 (setq user-mail-address "coon@@yoyodyne.com") | |
2203 @end example | |
2204 | |
2205 Various Emacs packages that need your own email address use the value of | |
2206 @code{user-mail-address}. | |
2207 | |
2208 @item | |
2209 Make Text mode the default mode for new buffers. | |
2210 | |
2211 @example | |
2212 (setq default-major-mode 'text-mode) | |
2213 @end example | |
2214 | |
2215 Note that @code{text-mode} is used because it is the command for | |
2216 entering Text mode. The single-quote before it makes the symbol a | |
2217 constant; otherwise, @code{text-mode} would be treated as a variable | |
2218 name. | |
2219 | |
2220 @need 1500 | |
2221 @item | |
2222 Set up defaults for the Latin-1 character set | |
2223 which supports most of the languages of Western Europe. | |
2224 | |
2225 @example | |
2226 (set-language-environment "Latin-1") | |
2227 @end example | |
2228 | |
2229 @need 1500 | |
2230 @item | |
2231 Turn on Auto Fill mode automatically in Text mode and related modes. | |
2232 | |
2233 @example | |
2234 (add-hook 'text-mode-hook | |
36148
a2719b6e7a2f
Don't use naked lambdas in examples. Fix bad @xref usage.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
2235 '(lambda () (auto-fill-mode 1))) |
25829 | 2236 @end example |
2237 | |
2238 This shows how to add a hook function to a normal hook variable | |
2239 (@pxref{Hooks}). The function we supply is a list starting with | |
2240 @code{lambda}, with a single-quote in front of it to make it a list | |
2241 constant rather than an expression. | |
2242 | |
2243 It's beyond the scope of this manual to explain Lisp functions, but for | |
2244 this example it is enough to know that the effect is to execute | |
2245 @code{(auto-fill-mode 1)} when Text mode is entered. You can replace | |
2246 that with any other expression that you like, or with several | |
2247 expressions in a row. | |
2248 | |
2249 Emacs comes with a function named @code{turn-on-auto-fill} whose | |
2250 definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler | |
2251 way to write the above example is as follows: | |
2252 | |
2253 @example | |
2254 (add-hook 'text-mode-hook 'turn-on-auto-fill) | |
2255 @end example | |
2256 | |
2257 @item | |
2258 Load the installed Lisp library named @file{foo} (actually a file | |
2259 @file{foo.elc} or @file{foo.el} in a standard Emacs directory). | |
2260 | |
2261 @example | |
2262 (load "foo") | |
2263 @end example | |
2264 | |
2265 When the argument to @code{load} is a relative file name, not starting | |
2266 with @samp{/} or @samp{~}, @code{load} searches the directories in | |
2267 @code{load-path} (@pxref{Lisp Libraries}). | |
2268 | |
2269 @item | |
2270 Load the compiled Lisp file @file{foo.elc} from your home directory. | |
2271 | |
2272 @example | |
2273 (load "~/foo.elc") | |
2274 @end example | |
2275 | |
2276 Here an absolute file name is used, so no searching is done. | |
2277 | |
2278 @item | |
37354
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2279 @cindex loading Lisp libraries automatically |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2280 @cindex autoload Lisp libraries |
38114 | 2281 Tell Emacs to find the definition for the function @code{myfunction} |
2282 by loading a Lisp library named @file{mypackage} (i.e.@: a file | |
2283 @file{mypackage.elc} or @file{mypackage.el}): | |
37354
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2284 |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2285 @example |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2286 (autoload 'myfunction "mypackage" "Do what I say." t) |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2287 @end example |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2288 |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2289 @noindent |
38114 | 2290 Here the string @code{"Do what I say."} is the function's |
2291 documentation string. You specify it in the @code{autoload} | |
2292 definition so it will be available for help commands even when the | |
2293 package is not loaded. The last argument, @code{t}, indicates that | |
2294 this function is interactive; that is, it can be invoked interactively | |
2295 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. | |
2296 If the function is not interactive, omit the @code{t} or use | |
2297 @code{nil}. | |
37354
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2298 |
39aa69a68098
(Init Syntax): Add a cross reference to "Non-ASCII Rebinding".
Eli Zaretskii <eliz@gnu.org>
parents:
37265
diff
changeset
|
2299 @item |
25829 | 2300 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}. |
2301 | |
2302 @example | |
2303 (global-set-key "\C-xl" 'make-symbolic-link) | |
2304 @end example | |
2305 | |
2306 or | |
2307 | |
2308 @example | |
2309 (define-key global-map "\C-xl" 'make-symbolic-link) | |
2310 @end example | |
2311 | |
2312 Note once again the single-quote used to refer to the symbol | |
2313 @code{make-symbolic-link} instead of its value as a variable. | |
2314 | |
2315 @item | |
2316 Do the same thing for Lisp mode only. | |
2317 | |
2318 @example | |
2319 (define-key lisp-mode-map "\C-xl" 'make-symbolic-link) | |
2320 @end example | |
2321 | |
2322 @item | |
2323 Redefine all keys which now run @code{next-line} in Fundamental mode | |
2324 so that they run @code{forward-line} instead. | |
2325 | |
26392
b3d3ff9a7a2c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25829
diff
changeset
|
2326 @findex substitute-key-definition |
25829 | 2327 @example |
2328 (substitute-key-definition 'next-line 'forward-line | |
2329 global-map) | |
2330 @end example | |
2331 | |
2332 @item | |
2333 Make @kbd{C-x C-v} undefined. | |
2334 | |
2335 @example | |
2336 (global-unset-key "\C-x\C-v") | |
2337 @end example | |
2338 | |
2339 One reason to undefine a key is so that you can make it a prefix. | |
2340 Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a | |
2341 prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix | |
2342 definition. | |
2343 | |
2344 @item | |
2345 Make @samp{$} have the syntax of punctuation in Text mode. | |
2346 Note the use of a character constant for @samp{$}. | |
2347 | |
2348 @example | |
2349 (modify-syntax-entry ?\$ "." text-mode-syntax-table) | |
2350 @end example | |
2351 | |
2352 @item | |
2353 Enable the use of the command @code{narrow-to-region} without confirmation. | |
2354 | |
2355 @example | |
2356 (put 'narrow-to-region 'disabled nil) | |
2357 @end example | |
2358 @end itemize | |
2359 | |
2360 @node Terminal Init | |
2361 @subsection Terminal-specific Initialization | |
2362 | |
2363 Each terminal type can have a Lisp library to be loaded into Emacs when | |
2364 it is run on that type of terminal. For a terminal type named | |
2365 @var{termtype}, the library is called @file{term/@var{termtype}} and it is | |
2366 found by searching the directories @code{load-path} as usual and trying the | |
2367 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the | |
2368 subdirectory @file{term} of the directory where most Emacs libraries are | |
2369 kept.@refill | |
2370 | |
2371 The usual purpose of the terminal-specific library is to map the | |
2372 escape sequences used by the terminal's function keys onto more | |
2373 meaningful names, using @code{function-key-map}. See the file | |
2374 @file{term/lk201.el} for an example of how this is done. Many function | |
2375 keys are mapped automatically according to the information in the | |
2376 Termcap data base; the terminal-specific library needs to map only the | |
2377 function keys that Termcap does not specify. | |
2378 | |
2379 When the terminal type contains a hyphen, only the part of the name | |
2380 before the first hyphen is significant in choosing the library name. | |
2381 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use | |
2382 the library @file{term/aaa}. The code in the library can use | |
2383 @code{(getenv "TERM")} to find the full terminal type name.@refill | |
2384 | |
2385 @vindex term-file-prefix | |
2386 The library's name is constructed by concatenating the value of the | |
2387 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} | |
2388 file can prevent the loading of the terminal-specific library by setting | |
2389 @code{term-file-prefix} to @code{nil}. | |
2390 | |
2391 @vindex term-setup-hook | |
2392 Emacs runs the hook @code{term-setup-hook} at the end of | |
2393 initialization, after both your @file{.emacs} file and any | |
2394 terminal-specific library have been read in. Add hook functions to this | |
2395 hook if you wish to override part of any of the terminal-specific | |
2396 libraries and to define initializations for terminals that do not have a | |
2397 library. @xref{Hooks}. | |
2398 | |
2399 @node Find Init | |
2400 @subsection How Emacs Finds Your Init File | |
2401 | |
29107 | 2402 Normally Emacs uses the environment variable @env{HOME} to find |
25829 | 2403 @file{.emacs}; that's what @samp{~} means in a file name. But if you |
38114 | 2404 run Emacs from a shell started by @code{su}, Emacs tries to find your |
2405 own @file{.emacs}, not that of the user you are currently pretending | |
2406 to be. The idea is that you should get your own editor customizations | |
2407 even if you are running as the super user. | |
25829 | 2408 |
2409 More precisely, Emacs first determines which user's init file to use. | |
29107 | 2410 It gets the user name from the environment variables @env{LOGNAME} and |
2411 @env{USER}; if neither of those exists, it uses effective user-ID. | |
2412 If that user name matches the real user-ID, then Emacs uses @env{HOME}; | |
25829 | 2413 otherwise, it looks up the home directory corresponding to that user |
2414 name in the system's data base of users. | |
2415 @c LocalWords: backtab |