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