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