annotate man/custom.texi @ 27218:ff77115434db

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